Thursday, December 11, 2008

Oracle Service Bus Migration (ESB to OSB)

Many customers have already build services with the Oracle SOA Suite. A part of these services are implemented with Oracle Enterprise Service Bus (ESB). After the acquisition of BEA System, Oracle introduced the new product; the Oracle Service Bus (OSB).

This product is positioned as standalone Service Bus. The ESB will be integrated into the new Oracle 11g SOA stack, and renamed into mediator as a component of the Service Component Architecture (SCA).

Business requirements can result that instead of using the ESB the OSB is required. This could result that customers already have implemented ESB services and they need to migrate to the OSB.

This article describes the approach on migration from ESB to OSB.

Migrating to the Oracle Service Bus requires knowledge of various technologies.
There are no tools yet for automatic migration of ESB services to OSB. That is why document give you best practise on this.

Tools that are used for the migration are:
  • Oracle JDeveloper
  • Oracle Workshop (Eclipse development)

Oracle JDeveloper
Oracle JDeveloper is use to view the ESB services. It is used to determine the dependencies of the artefacts that it is using.

Oracle Workshop
Oracle Workshop is used to build and deploy the new OSB services.

While there is no automatic migration, we need to rebuild the services in OSB. The approach is as follows.

Reuse the artifacts from ESB as much as possible. This means in practices that we will reuse the WSDL definitions, schema definitions and style sheets.

Open in JDeveloper the ESB services and determine the artifacts it is using;
  • WSDL files
  • XSD schema's
  • Used elements
  • Used namespaces
  • Stylsheets
  • Filters
  • Adapters
Describe for each ESB service the artifacts in structured way; for example in a table format:

Based on these artefacts, the OSB services can be build.

Development environment
Depending on the complexity of the OESB services, a different sequence of steps should be followed. First of all a project structure should be in place. In this project structure various components will be stored.

The Workspace (OSB Project Structure) should contain one OSB Configuration Project, give this configuration a name "MyOSBConfig" and an OSB Project called "MyOSBMigration". The former contains the server definition for an OSB Server running on :, the latter all project resources.

Folder Structure
Create for every ESB service, an OSB service with the following directory structure.
Schema <SchemaFile>
Element <elementused>
Schema <SchemaFile>
Element <elementused>

BusinessServiceAll the business services are located here.
ProxyServiceAll the proxy services are located here.
SchemaLocal schema's in the project are located here.
TransformationLocal transformation files (XSLT & XQuery).
WsdlThe interface definitions.

For each ESB project copy the used XSLT files into the transformation directory.

Naming Convention
A recommended approach for naming conventions of OSB resources is to add the
prefix `PS_' for Proxy Services, `BS_' for Business Services, `XQ_' for XQuery
transformations, and append a version indication `_v1r0'. Examples:

Project: CollectOrderInformation
Proxy service: PS_GetOrder_RS_v1r0

Bus. Service: BS_GetOrder_v1r0

Proxy Endpoints:
The enpoints of the proxy services will be renamed to


Common Schemas
All schemas of the Common data Model are imported in the OSB project in folder Common/Schema/. All generated or imported WSDLs should preferably refer to these schemas, potentially importing service specific schemas in the "Schema" folder of the respective service.

Based on the pervious table the OSB service can be build. Execute the following steps to perform this.
  • Create the business services
  • Create the proxy service
  • Implement the message flow
Create the business services
Create a new business service for each output definition. If an external web service is called, import or consume the WSDL definition of that web service. The same applies if this service is a BPEL process. In this case some additional changes should be made, this is described in the next paragraphs..

If you are calling a BPEL process, you could use the BPEL transport instead of normal http protocol. The BPEL protocol is more efficient implementation on calling BPEL from OSB.

When the business service is created, the WSDL and schemas are copied into a folder of your project. After creating the business service move the WSDL files to the WSDL directory and the schemas to the Schema directory or to the Common/Schema directory.

Note: With BEA ALSB 3.0, you should remove the partner link bindings, otherwise the WSDL is invalid. This is fixed in OSB 10gR3.

Create the proxy service
Create a new proxy service for each input definition. If the service is based on a interface definition from an external web service is called, import or consume the WSDL definition of that web services.

When the proxy service is created, the WSDL and schemas are copied into a folder of your project. After creating the proxy service move the WSDL files to the WSDL directory and the schemas to the Schema directory or the Common/Schema directory.

Implement the message flow
Implementing the flow is the most important step of the migration. Based on the various output from the ESB, you should route the message to the various business services.

The most simple one is just create a routing node to call the services.
Often we need a transformation call the business service
In the replace action we define the transformation., this is based on the style sheet of the ESB.
When there are filters defined in ESB service, this can be replaces in OSB via If-Then actions or conditional branches actions.

Note that there can be issues with style sheets. The style sheet is based on the JDeveloper diagrammer, it is using namespaces and namespace aliases based on the interface definition of the ESB. Execute the test action on the replace action of the Oracle Workshop (Eclipse).
It could be that the style sheet is using Oracle SOA specific extensions or custom functions, these are not available in OSB. If this is the case, you should change the style sheet or, which is easier, create a XQuery transformation.

Deployment and Test
Deploy and test the OSB service, you could use various test scenarios and tools to perform this.
  • Test style sheets and XQueries from Eclipse.
  • Test business services from the OSB Console.
  • Test proxy services from the OSB Console.
  • Use tools such as SoapUI to perform end-to-end tests.

Database Adapter
Note that the current version of OSB does not have a DB adapters as in the ESB.

Therefore you should create the DB adapter in BPEL as a simple wrapper for this
query. The BPEL process should use the same input and output schema's and namespaces as generated in the partner link of the DB adapter. The future version of OSB 10gR3 will have support of the DB adapter.

JMS Adapter
The OSB has full support of the using JMS messaging.

Import WSDL from BPEL
The ESB service has both the Proxy Service as the Business Service based on the same WSDL that is `consumed' from the BPEL process. The steps to create a similar service in OSB are:
  1. Import the WSDL from the BPEL process URI (?WSDL) by consuming froma URI. All included schemas are imported as well and stored in the samefolder.
  2. Leave the WSDL itself in the `WSDL' folder.
  3. Drag and drop the service specific schema to the `Schema' folder thereby automatically changing the reference in the WSDL.
  4. Change the references from either the WSDL or the service specific schema to the CDM schemas by changing the "schemaLocation" property of the "import"tag.
  5. Remove the imported CDM schemas from the `wsdl' directory.
  6. Add a Business Service in the `BusinessService' directory based on the imported WSDL.
  7. Add a Proxy Service in the `ProxyService' directory based on that same WSDL.
  8. Add a `Routing Node' to the Proxy Service and route to the Business Service.

Imported WSDL from ESB
The ESB service has a Proxy Service based on a ESB "generated" WSDL and the Business Service based on the WSDL of a BPEL process. The steps to create a similar service in OSB are:
  1. Import the OESB "generated" WSDL in the Workspace `wsdl' folder.
  2. Add a "service" and a "binding" to that WSDL, because the WSDL is not well-defined, refer to the PortType of the WSDL.
  3. Create a Proxy Service in the `ProxyService' directory based on that WSDL.
  4. Import the WSDL from the BPEL process as described for the previous service migration; don't forget to move the schemas.
  5. Add a Business Service in the `BusinessService' directory based on the imported WSDL.
  6. Add a `PipelinePair' to the Message Flow of the Proxy Service.
  7. In the request Pipeline, add a `stage' with a `replace' action, change the XPath to `.', enter variable `body', in the expression select the XSL file and add the rootelement of the body (request) to the `Binding' box, check `replace node contents'.
  8. Same for the response `Pipeline', but obviously for the response XSL and the response rootelement.
  9. Add a `Routing Node' to the Proxy Service and route to the Business Service.

Friday, December 05, 2008

Deploy to Oracle Service Bus does not work

When deploying services from Oracle Workshop (Eclipse) to the Oracle Service Bus (OSB) fails when you did an out-of-the-box installation. Eclipse is responding with:

While the log file of the OSB Server is like this:

<Error> <ConfigFwk> <BEA-390101> <Activation of session OSB_Publish failed: com.bea.wli.config.deployment.server.ServerLockException: Failed to obtain WLS Edit lock; it is currently held by user weblogic. This indicates that you have either started a WLS change and forgotten to activate it, or another user is performing WLS changes which have yet to be activated. The WLS Edit lock can be released by logging into WLS console and either releasing the lock or activating the pending WLS changes. com.bea.wli.config.deployment.server.ServerLockException: Failed to obtain WLS Edit lock; it is currently held by user weblogic. This indicates that you have either started a WLS change and forgotten to activate it, or another user is performing WLS changes which have yet to be activated. The WLS Edit lock can be released by logging into WLS console and either releasing the lock or activating the pending WLS changes. at com.bea.wli.config.deployment.server.ServerDeploymentInitiator.__serverCommit(Unknown Source) at com.bea.wli.config.deployment.server.ServerDeploymentInitiator.access$200(Unknown Source) at com.bea.wli.config.deployment.server.ServerDeploymentInitiator$ Source) at at Source) Truncated. see log file for complete stacktrace

The reason for this error, is the fact the OSB is configured for automatic apply of changes made OSB. This option is default in OSB 10gR3 and should be switched off. This can be done via the WLS console.

  • Logon to Console
  • Select Preferences
  • Uncheck the option "Automatically Acquire Lock and Activate Changes":
  • Click on Save
  • Activate Changes

Monday, December 01, 2008

Remove namespaces in OSB and BPEL/ESB

Removing name spaces from your XML payload is sometimes needed. Various reasons require this. This article shows you how to remove namesapces in your XML payload. There are two solutions.

XML Stylesheets (XSLT)

For BPEL and ESB you can use the XSLT solution to remove namespaces. The next example show you how to implement this in BPEL. First of all we need to create a XSLT file. The file shoudl looks like this:

<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet version="1.0" xmlns:xsl=""
<xsl:template match="comment()|processing-instruction()|/">
<xsl:template match="*">
<xsl:element name="{local-name()}">
<xsl:apply-templates select="@*|node()"/>
<xsl:template match="@*">
<xsl:when test="name() != 'xmlns'">
<xsl:attribute name="{local-name()}">
<xsl:value-of select="."/>
The BPEL code to call this XSLT is as follows.

<assign name="Transform_1">
<from expression="ora:getContentAsString(
, bpws:getVariableData('inputVariable','payload'))
<to variable="outputVariable" part="payload"

The above example will remove the namespaces from the input payload, then it will convert it to a string and put the output into the result element.


The solution for OSB can alo apply via XLST, but in OSB the XQuery technology is used.. Removing the namespace in XQuery is done via the following function.

declare namespace xf = "";

declare function xf:strip-namespace($e as element())
as element()
element { xs:QName(local-name($e)) }
for $child in $e/(@*,node())
if ($child instance of element())
then xf:strip-namespace($child)
else $child
You can call this function in your XQuery file as follows.
concat('<?xml version="1.0" encoding="UTF-8"?>', fn-bea:serialize(xf:strip-namespace($varMessage)))

Friday, November 14, 2008

OSB standards and guide lines

After implementing some OSB projects I want to share some guidelines that I'm using on this projects. Like BPEL you need to have define some standard naming conventions, to make your application maintainable, shareable and explainable to customers.

The following naming convention should be used:

Proxy services
Every proxy service should start with the PS_ prefix, followed by the functional name and ends with a verion and release number.


End points
The end point of the proxy service should be changed to


Business services
Every proxy service should start with the BS_ prefix, followed by the functional name and ends with a verion and release number.


Discover all the services that need to be implement for OSB. Catelog the services in a category. This category is used as OSB project to collect the proxy services and business services. There is one special category; common..

The structure of a category is as follows:
Common objects
Objects as such as XSD files, xqueries, xslt etc, that are used in more then one proxy / business services are stored in the common category.

In OSB actions are executed in the message flow of the proxy service. Each action has a default name. Rename each action into the following format.

For example

Tuesday, November 11, 2008

Handle multiple operations in OSB

In the old days of Oracle ESB, we could defined WSDL services with multiple operations. Is the OSB you do the same. Nothing new so far. But when you create a proxy service based on the multiple-operation WSDL, you will get an error "OSB Kernel:398034".

OSB Kernel:398034]Two operations expect the same incoming message, you must use a selector different than message body.

This error cna be fixed, by selecting a different "Operation Selection Configuration". This can be done by selecting your proxy-service and select the "Operation" tab sheet in Eclipse Workshop. Here you determine how algorithm of the operations are handled.. In our case select 'SOAPAction Header'.

Tuesday, November 04, 2008

Who is the best OSB or ESB?

A lot of rumors pass along today. After the take over of BEA what is the strategy of Oracle regarding the products. Within our Oracle SOA world the issue raised what will happen with Oracle ESB compared with the Oracle Service Bus (also known as Aqualogic Service Bus).

Both Oracle products, ESB and OSB are strategic for Oracle. The ESB will still be availalble in the next going releases; and release 11g. In release 11g the ESB will be acting as the mediator in the SCA environment and fade away in the next releases of 11g as an ESB seperate component. Activities as routing will still be availble within the SCA of SOA 11g. The Oracle Service Bus is positioned as a standalone service bus within the SOA Suite and will more and more integrated in the SOA Suite release 11g.

So, are there any differences between ESB and OSB. IMHO there are off course, but depending on your business requirements and technical background you would chose OSB or ESB. Here is my view on the two products.
Routing+++OSB:+Split join
Transformation: xslt+++OSB: only xslt runtimes upport
Transformation:xquery +ESB:Does not have XQuery
DMV/Xref+noteOSB will support DMV/Xref in FMW11
Technology adapters design time+++OSB: full support techology adapters as of
JCA Framework++OSB: JCA support as of10gR3
HA+Clustering++ +OESB: AS Clusters EoL 2012
Message Validation+ ++OSB: Stringer Schema/wdsl validation
Error Handling++ +OSB: Much richer error handling
BPEL Integration++OSB: BPEL suport in OSB 3.1
XA Support++ +Pipelines transactional / QoS on Proxies
Resumittance failed messages+ OSB: is stateless
Instance Monitoring+++OSB: Stateless: No concept of an “instance”
“SLA” Dashboard +OSB: # succesfull/failed message
Performance Tuning++ +OSB:Throttling
Track Record++OSB exists longer, more implementations

New features of Oracle Service Bus can be found here.

Thursday, October 09, 2008

Import WSDL definitions in Oracle Service BUS

With the Oracle Service Bus the Oracle Workshop is supplied to the develop services. The workshop is based on Eclipse. When developing BPEL processes with JDeveloper, you could easily import WSDL's from other systems by using local file definitions or directly via the URL. Using the URL option, give you the advandtage that also the import XSD are read. Wit JDeveloper this was done automaticly. The tutorials of the Oracle Service Bus Workshop, assumes that you are using local files for the XSD and WSDL definitions.

It is possible to read the WSDL defintions directly from the URL (URI). This is done as follows, assuming you have opened the workshop, create an ALSB service with all the folders.

Right click on the Proxy Folder -> New -> Proxy Service

In the Next window and the appropriate values, and click on "Next".

In the next screen select WSDL and click on browse. Click in Consume to load an external WSDL definition.

The next screen shows you the WSDL definitions already known in your project

In the next screen, Select from the " Service Consumption" the URI option, enter the WSDL URL and click on 'Ok'. Now the WSDL files and XSD are loaded into your sevice definition.

Note: When you load WSDL definitions from BPEL, you should remove manually the partnerlinks in your OSB project. See also this article.

Oracle Service Bus (aka ALSB): Can not deploy service

Two nice articles are published related to Oracle Service Bus (OSB), previous known as BEA Aqualogic Service Bus, when you using the OSB to call a BPEL process. The first error you get when you want to access BPEL process is:

An unexpected error occured accessing information about the WSDL of the service:
com.bea.wli.config.component.NotFoundException: Can not compute effective WSDL for : BusinessService Chapter19/BusinessServices/AddIntegers

The solution of this error is described by Berthold Maier’s Weblog and Anthony Reynolds blog. Just remove the partner link definitions from your BPEL WSDL:

<plnk:partnerLinkType name="HelloWorld">
<plnk:role name="HelloWorldProvider">
<plnk:portType name="tns:HelloWorld"/>

Wednesday, October 01, 2008

Weblogic: Configure users for Worklist Application

After applying Oracle SOA Suite on top og Weblogic 9.2, all functionality is available. There is a minor issue with the worklist application. The users and roles are not available in the Weblogic Realm. This is because Weblogic is using a ligh-weight LDAP server to store users and roles and policies. The users in the Human Task Worklist are not populated to this LDAP server.
It can only be solved by configure the JAZN of SOA Suite to use an LDAP server and WebLogic as well. This is written in the installation documentation of SOA Suite on Weblogic. But there is a not supported solution to add users to the worklist application.

To see the users that are available in the jazn XML based store you should go to

cd $BPEL_HOME/j2ee/home

and run command :

$BPEL_HOME/jdk/bin/java -jar jazn.jar
-user oc4jadmin -password welcome1 –listusers

Note: Please use the appropriate username and password)

The location of the jazn based XML store is:


To create users (in this case weblogic) that are also configured for BPEL tasklist, you should add the user to the jazn XML store by using the following command:

$BPEL_HOME/jdk/bin/java -jar jazn.jar -user oc4jadmin
-password welcome1 -adduser weblogic weblogic

And also create the appropriate user properties in :


To have the worklist use JAZN based authorization the content of is_config.xml (located in $BPEL_HOME/bpel/system/services/config) should be :

<?xml version = '1.0' encoding = 'UTF-8'?>
<ISConfiguration xmlns="">
<configuration realmName="">
<provider providerType="JAZN" name="XML" service="Identity">
<property name="usersPropertiesFile" value="users-properties.xml"/>

Additional jazn commandsare:

java -jar jazn.jar [-user <username> -password <password> -clustersupport <oracle_home>] [command]

-listusers [<realm> [-role <role>|-perm <permission>]] |
-listroles [<realm> [<user>|-role <role>]] |

Thursday, September 18, 2008

SOA FAQ: Compare Weblogic and Oracle Application Server

Migrating from Oracle Application Server to WebLogic for the Oracle SOA Suite is not rather complicated, the concept is still the same. The major difference is the look and feel of the WebLogic Administration console and all the option you can choose. Furthermore the whole directory structre and filenames are different. This article gives you a quick reference on the difference

How to install Oracle SOA Suite on WebLogic?

Currently Oracle SOA Suite is certified against Weblogic 9.2. The near future Oracle SOA Suite will be certified against 9.2.
  • Install Oracle SOA Suite 10.1.3.x in seperate home.
  • Install Oracle SOASuite patch.
  • Upgrade SOA Schemas
  • Apply Opatch for Bug 7337034
  • Download SOA Suite for WebLogic via OTN (WL_SOA10134_Installables).
  • Install Weblogic 9.2
  • Unzip WL_SOA10134_Installables
  • Apply changes in (create new domain)
  • Install SOA Suite for WebLogic

How to start WebLogic with Oracle SOA Suite installed?

WebLogic is using a node manger to control the environment. This can be compared with the Oracle process manager (OPMN). Start the node manager as follows:


WebLogic has the concepts of domains. This is NOT the sames as the domains in the the SOA Suite. In a Domain one or more application servers are running. At least one is configured, this is the mananged server, it is comparable with the OC4J instance 'home'. You can start this server as follows:


Within the installtion of Oracle SOA Suite on top of Weblogic, a addtional server is created. This can be compared with the 'oc4j_soa' container .

Where is the data-sources.xml file located?

Each connection is has his own config file instead of one single file.

Where are the adapter config files, such as oc4j-ra.xml?


Every change made in the Weblogic Admin Console comes in to a deployment plan file (Plan.xml).

Where can I find my log files, the standard out for example?


How do I edit the adapter config files?

Just edit the weblogic-ra.xml file. From the console you can not edit empty properties (wls 9.2)


Wednesday, September 17, 2008

Oracle SOA Build System: updated

An updated version of Oracle SOA Build System can be download here. This version should work against Oracle SOA Suite release

A next version of this tool will work against Oracle Weblogic Server.

Featured plan:
  • Migrate OSBS tool for Oracle Weblogic server (
  • Migrate OSBS tool for Oracle Weblogic server (
  • Migrate OSBS tool for Oracle Weblogic server (11.x)


Tuesday, September 16, 2008

Install Oracle WebLogic Server / Oracle Application Server on linux 64 bit

Not all Oracle products are directly available on Linux 64 bit. This results, that you can not use the product or trust the 32 bit version.

To use the 32 bit products on a 64 bits operating system, you must have installed the 32 bit packages. With tools such as YAST or another package managers, you can easily add these packages:
  • linux32
  • compat-32bit
  • gcc-32bit
  • glib-32bit
  • glibc-32bit
  • and other dependencies
To install the 32 bits code on the 64bits O/S you first start the 32 bits shell.

$ linux32 bash

Then start your scripts, for example:




Applying Oracle Patches on WLS

While I'm now working on Oracle Web Logic server; WLS 9.2, Oracle SOA Suite and Oracle Service Bus. I run into a common issue when applying patches on your Operating system.

I love to play with Linux, my version is Suse 11.1. I known it is running on the edge, but thats live.

When applying patches you some times get errors like:

OPatch detects your platform as 46 while this patch 7337034 supports platforms:
0 (Generic Platform)

IMHO the patch should just install, while the patch is generic.

A simple solution is available.

Open the file etc/config/inventory from your install directory.

Add your platform into this file and apply the patch again.

<platform name="Generic Platform" id="0">
Add your platform:
<platform name="Generic Platform" id="46">
<platform name="Generic Platform" id="0">

Monday, September 01, 2008

Domain Value Mapping (DVM) example

Here are some examples how to use domain-value-mapes in XSLT transformations.

Domain value maps are used to map code-values from one into another one. Commonly used in SOA patterns and in canonical datamodels.

For example in Oracle AIA, DVM are used to map statuses farom Siebel to AIA canonical data format and then to Oracle BRM format.

Example call to DVM lookup

<xsl:variable name="Salutation" select="orcl:lookup-dvm('CONTACT_SALUTATION','SEBL_01','Miss.','PMDM_01','')">
<xsl:if test="$Salutation!=''">
<xsl:value-of select="$Salutation">

In more general terms:

<xsl:variable name="RESULT" select="orcl:lookup-dvm(DVM_NAME,$SOURCE_SYSTEM,$KEY,$TARGET_SYSTEM,'')">
<xsl:when test="$ RESULT!=''">
<xsl:value-of select="$ RESULT ">

‘SOURCE_SYSTEM’ variable either retrieved from EBM Header and lookup in AIA registry OR hard-coded to ‘COMMON’ (when message from AIA to application

‘TARGET_SYSTEM ‘ would be a target system either retrieved from EBM Header and lookup in AIA registry or hard-coded to ‘COMMON’ (when message from application to AIA’

Lookup in AIA registry example:

<xsl:variable name="TargetSystemID">
<xsl:when test="boolean(/telcocustmr:CreateCustomerPartyEBM/corecom:EBMHeader/corecom:Target/corecom:ID/text())">
<xsl:value-of select="/telcocustmr:CreateCustomerPartyEBM/corecom:EBMHeader/corecom:Target/corecom:ID">
<xsl:value-of select="aia:getServiceProperty('{}CreateCustomerPartyPortalProvABCSImpl','BRMCUSTService.Routing.Target.Default.SystemID',true())">

<xsl:variable name=" SOURCE_SYSTEM " select="$TargetSystemID">

Note the way the identification of the system is used BRMCUSTService. If your application is not (yet) registered in AIA, like PMDM, a hardcoded system identification would be more appropriate, example:

<xsl:variable name="TargetSystemID">
<xsl:when test="boolean(/telcocustmr:CreateCustomerPartyEBM/corecom:EBMHeader/corecom:Target/corecom:ID/text())">
<xsl:value-of select="/telcocustmr:CreateCustomerPartyEBM/corecom:EBMHeader/corecom:Target/corecom:ID">

<xsl:variable name=" SOURCE_SYSTEM " select="$TargetSystemID">

Friday, August 22, 2008

Oracle SOA Suite and proxies settings

One of the biggest pitfall when executing projects based on SOA technology is the proxy settings in the environment.

Proxies are set on the workstation to guide the user to the Internet via this proxies. Companies uses this to monitor traffic and content but also for filtering the content.

When installing the SOA Suite or JDeveloper on your workstation, you mostly forget this. After installing JDeveloper and/or SOA Suite check that the proxies are disabled.

  • In JDeveloper check the preferences
  • In Oracle SOA Suite server, check the 'opmn.xml' config file.
This pitfall is also valid on the server. After installing check that the proxies are note set.

  • In Oracle SOA Suite server, check the 'opmn.xml' config file.
  • In the enviroment variables, should be unset.

Tuesday, August 12, 2008

Oracle SOA Build System: The docs

I have updated my documents related to my Oracle SOA Build System. The build tool to compile, deploy any SOA component (BPEL, ESB, Human Tasks, AIA, Java) for any environment to your Oracle Application Server, independed of an existing software installations .

I have created two new documents:



Monday, July 07, 2008

Deployment too fast?

When doing configuration management on your SOA application to various environments; development, test, acceptance and production. You would use you on mechanism for deployment.

What I found out during some SOA projects, that your build system is too fast for the de Oracle SOA Suite server. When deploying a lot of BPEL processes and ESB services, you sometimes get strange errors. This is related that WSDL files cannot be found or strange errors when registering ESB services. The solution is very simple.

Introduce a wait time between each deployment. Choose this delay between 4 and 10 seconds.

After deployment, the system needs to take care that everything is in place. This will take some time. Therefore a new deployment directly after the previous one, could result in errors.


Friday, June 13, 2008

Application Server: Rotating log files

After a out of the box installation and configuration of the Oracle Application Server, most of the log files of the AS are configured to be rotated. This means that after a period or when they reach a particular size, the log file is copied and a new log files is created.
This gives the AS administrators flexibility to maintain these files; backup etc..

There is one log file, the so called standard output / standard err, also known as print output to console, that is not configured to be rotated. But this files is growing and growing, it could easily grow into hundreds of giga bytes.

The name of this files is:


It is possible to make this file rotatable.

Add the following parameters in the configuration of your OC4J instance,

In java-options:


Note: 8 means, rotate after 8 MB in size.

In oc4j-options:

-out $ORACLE_HOME/opmn/logs/oc4j_soa.out
-err $ORACLE_HOME/opmn/logs/oc4j_soa.err

Seperate standard outout and error messages.

See also the Oracle docs on this.

Sunday, June 01, 2008

Oracle SOA Build System: Web Enabled

The Oracle SOA Build System is based on a (L)unix script. The script will validate the input parameters and then call the Ant build tool. To deploy and or compile the SOA code to the application server.

Using this script, you need access to the server on which the script is available and configured. You also need some basic (L)unix commands to execute the task of the build system. Sometime administrators are not willing to give access to those systems, even if the access privileges are low.

Access to the Oracle SOA Build System via a WEB interface makes it more user friendly and less failures in the usage of the tool.

I have looked on the Net to integrate the build tool in other tools that are used in continuous integration. Tool such as CruiseControl are very useful. But most of these tools are working around a single environment; development. We I was looking for was a web interface in which I can use the full functionality of the build tool.

I did a project were we integrate the tool in CruiseControl, but it did not give me the flexibility of the tool itself.

Now a few new files have been created to enable the obbuild system to be executed from the browser. This result that the interface is very simple and everyone can use it. The next screens shows you some examples. The interface is simple but effective.

Download the latest version from your source control system.

Deploy the SalesOrderEBS to the ESB server.

Undeploy a BPEL process.

Download it here

Monday, May 26, 2008

The build tool; deploy AIA / BPEL / ESB / Workflow / Java using ANT

A few years ago, when Oracle had only the BPEL component, deployment was rather complex. Therefore I create my own build tool, replacing the obant tool and ignoring the existing build.xml files, supplied within your JDeveloper project.

Meanwhile, the tool has been extended during the implementation of projects. Every time, I was focussing that the tool should be independent of customer needs, making it generic.

In general development of BPEL processes is done via an IDE tools. These tools are:
  • Oracle JDeveloper 10g (
  • obant tool.

The first product is a graphical tool to design and develop SOA components. The tool can also be used for compilation and deployment of a BPEL process for example. The obant tool is part of the BPEL software stack and can be used to compile and deploy a BPEL process. Combining these tools make is in general enough for designing and implementing BPEL applications.
It will be more complex if design and development must be done for various environments; developing new BPEL applications in development environment and fixing BPEL processes in a production environment.

The obant tool can compile from a current directory an ANT build.xml file. It will read the XML tags from this and interpret them. Oracle Jdeveloper generates this build.xml file when a new BPEL process is created. It is possible to extend this "build.xml" file with other ANT tasks. But this is not logical. When developing BPEL applications, it will result in many BPEL processes, each having it's own "build.xml" file.

A solution could be to have a general "build.xml" that is able to compile the BPEL processes.
A feature of the current obant tool, is that is only possible to use the core ANT tasks. It is not possible to use the optional tasks or even extend it with other tasks without changing the obant script.

The solution described in the next paragraphs will take this into account.

The build tool covers the following features and can be easily change and extended to customer requirements:
  • Using full ANT tasks features, Ant 1.7 + Ant-Contrib tasks
  • Support of Multiple environments; Dev / Test / Acceptance / Production / ...
  • Compiling BPEL processes
  • Deploy BPEL processes
  • UnDeploy BPEL processes
  • Register ESB services
  • Unregister ESB services
  • Deploy AIA BPEL processes
  • Deploy AIA ESB services
  • Integration with SubServersion; download latests or tags
  • Stand-alone tool ; not depending on Oracle installation
  • Compile and Deploy Java programs
  • Supporting 'MakeAll'
  • Import XREF values
As shown in the list of functionalities, the build system is now able to deploy AIAESB services. Therefore the build system is extended with AIA functionality. This means that AIA specific libraries have been added to the 'lib' directory of the build system. The unix script,, has been changed to add specific files.

Pre-Requirements AIA only
To deploy a complete set of AIA custom developed services or single ones, you must verify that you meet the following requirements. You must have correct file permissions for AIA:

To deploy an ESB service on the linux machine, as a non oracle owner is possible. The ANT script along with the ESB service, does need specific read/write settings.

Make user that the following directories and files are open for read/write, (recursively):


To use the build tool some configuration must be made. Most of all settings are located in properties files. Configure the build tool configuration file to prepare the deployment for this release. Edit the following file:


In build.env, edit ANT_HOME and ANT_JAVA_EXTENSIONS, change the first part of the path to where the package was copied to ($BUILD_TOOL). Also change LOG_DIR in build.env, log files will go to this directory.

An example of this file is here

# AIA_HOME is needed for AIA Specific deployment
export AIA_HOME=/app/oracle/product/AIA2.0

Manual Deployment
To deploy a the AIA components manually the following steps should be executed in this sequence.

Download the latest version of the AIA components. Example for SystemTest environment: -e test Download

Example for tag 2.0.23 being the current version for acceptance: -e acc Download 2.0.22

Promote is a task that does a find and replace on the source code. It was build for replacing endpoints but the tool can find and replace almost anything in source code.

Example; promote the existing download for the test environment -e test Promote

Note: it will use the file to execute the find and replace.

The file is used for a general replacement of tokens
in BPEL projects. The file describes hoe tokens can be replaced in one or
all BPEL processes, ESB services.


Replace in all BPEL files localhost:9700 into

Replace in HellWorld bpel process the default domain and the hostname

XSD files (AIA related)
The AIA environment is using static XSD files that are located on the application server in the directory:


Make sure that the latest version of the XSD files from SubVersion ($SVN_HOME/aia/xsd)are copied to this directory.

note: make sure the right privileges are applied on the server see DeployAIAXSD

A zip file is created with the XSD of AIA. You can now copy and unzip the file on the server.

Deploy generic ESB service
Note that before deploying the ESB service, the services will be undeployed. Based on the property file The GUID is read from this file. If the ESB service exists in this property it will be undeployed. Maintain this file if any new ESB services are added to the system

Deploy each ESB service separately, if they exists. Example for Test environment: -e test DeployESB HelloWorldEBS

Deploy generic BPEL process
Deploy each BPEL process separately. Example for Test environment:

For example: Compile and Deploy Helloworld 1.0 to the default domain -e test Compile HelloWorld -e test DeployBPEL HelloWorld 1.0 default

For example: Compile and Deploy Helloworld 1.1 to the MyDomain domain -e prod Compile HelloWorld -e prod DeployBPEL HelloWorld 1.1 MyDomain

Deploy AIA ESB service
Note that before deploying the ESB service, it will be undeployed. Based on the property file The GUID is read from this file. If the ESB service exists in this property it will be undeployed. Maintain this file if any new ESB services are added to the system

Deploy each AIA ESB service separately.

For example for Test environment: -e test DeployAIAESB SalesOrderEBS

Deploy AIA BPEL process
Deploy each AIA/BPEL process separately.

For example for Test environment: -e test CompileBPEL UpdateOrderSiebelProvImplABCS -e test DeployAIABPEL UpdateOrderCordysProvImplABCS 1.0 default

Deploy Java WebService
Deploy each Java process separately. Example for Test environment: -e test DeployJava HelloJavaWorld

Note: default-application.xml must be included in source code.

Automatic Deployment
To deploy the whole system at once, use the task 'MakeAll'. -e test MakeAll

Note: This target is using the '' that describes the correct sequence of all the AIA components (Java, BPEL, and ESB) that will be built and deployed. The next table shows an example of the '' file.
# Java

Command line interface
The command line interface of the obbuild tool is as follows: -? [-[hvtV] [-e environment] [-f build-file]
[-r replace-file] [task] [arg1] [arg2] .. [arg6]]

-h Shows this help
-V Show the version of this program
-t Show all the tasks in the build file
-e Select envirnonment property file,
default 'dev', reading

-f Read a specific build file, default is build.xml
in current directory

-r Read a specific replacement file,
use for promoting BPEL process to other environments.

-v Show verbose output
task The task to be executed, default is main
arg1..6 Optional arguments passed to the build file
as properties ANT.ARG1..ANT.ARG6

The tasks the build tool can execute: -t Tasks in ./build.xml
CompileBPEL - Compile one or all BPEL processes (
[arg=bpel-process-name] arg2=version])
Download - Download latest source code
CreateWar - Create WAR file, containing all
the BPEL processes
CreateEar - Create BPEL ear file
main - Default task
Promote - Find/Replace on one or more BPEL processes,
DeployAIABPEL - Deploy one or all AIA BPEL processes to a
domain on a remote server
arg2=version arg3=domain]
DeployBPEL - Deploy one or all BPEL processes to a domain
on a remote server
arg2=version arg3=domain]
DeployESB - Deploy one or all ESB services to a system
on a remote server
[arg1=[ESB-process|all] [arg2=system]]
CompileJava - Compile Java files
[arg1=name of the application]
WARJava - Create WAR file from class files
[arg1=name of application]
EARJava - Create EAR file from WAR file
[arg1=name of application]
DeployJava - Deploy an EAR file to OC4J container
[arg1=name of the application]
MakeAll - Create a new set of the application
[arg1=[bpel/esb version] [arg2=BPEL domain]
DeployAIAESB - Deploy one or all AIA ESB services
to a system on a remote server
[arg1=[ESB-process|all] [arg2=system]]
SendMail - Send a mail
[arg1=to arg2=subject arg3=text]
DeployAIAXSD - Deploy the AIA XSD files: creating a ZIP files
UndeployBPEL - Undeploy a BPEL process
[arg1=processname [arg2=version] [arg3=domain]]
UndeployESB - Undeploy one or all ESB services to
a system on a remote server
[arg1=[ESB-process|all] [arg2=system]]

You can download the (old version) zip file here, the zip file is as is. No support from Oracle or myself.

Tuesday, May 20, 2008

KPN Gone live with Oracle AIA

It's always nice to be part of a project that goes live. But even more when news agencies making attention on it. This time the Dutch KPN telecommunication provider, implemented successfully a large project based Oracle Application Integration Architecture (Oracle AIA).

Read the full article on CNN.

Some background (dutch)

Friday, April 11, 2008

Undeployment of BPEL process and ESB Services

With Oracle SOA Suite and Oracle AIA the whole development process is regulated with ANT. Wir SOA Suite we were able to deploy BPEL and ESB processes. What we missed was the possibility to undeploy these services.

If you are using Oracle AIA Foundation your are able to undeploy these services. This van be done via ANT extension, which are developed along with AIA.

To undeploy a BPEL process you use the following task:

To undeploy a ESB service you use the following task:
<service guid="${guid}"/>

Note the the GUID for the ESB service is the unique identifier of the service in the ESB system. This can be viewed in the database (wf_event).

Wednesday, April 09, 2008

Using dynamic endpoints in AIA

Oracle AIA adds some nice features on top of the Oracle SOA Suite. One of these things is using dynamic endpoints. This is a common feature in Oracle SOA Suite, but AIA makes it easier to maintain and use.

All generic properties of AIA are located in a property file. This file is called "AIAConfigurationProperties.xml". This file can be changed at runtime and can be reloaded to make it immediate available. This is done via the AIA Business Service Repository, the BSR.

Changing SOAP endpoints at runtime makes configuration management much easier. You can maintain multiple AIA configuration files for each environment; development, test and production.

To use this mechanism in your own BPEL processes the following actions must be taken:
  • Create entry in AIAConfigurationProperties.xml
  • Reload AIAConfigurationProperties.xml file
  • Import meta data xsd file in your BPEL WSDL file
  • Create namespace in BPEL file
  • Add to variables in your BPEL file
  • Retrieve end-point from AIAConfigurationProperties.xml
  • Assign entry to variable
  • Overwrite default endpoint.

Create entry in AIAConfigurationProperties.xml
Enter a new entry in the configuration file:

Reload AIAConfigurationProperties.xml file
Goto the BSR application and reload the application config file.
  • http://hostname:portnumber/AIA
  • Goto Setup
  • Goto Configuration
  • Click on Reload
Import meta data xsd file in your BPEL WSDL file
Add the following line in your BPEL WSDL file.


Create namespace in BPEL file
Add the following namespace defintion in your BPEL process.

Add to variables in your BPEL file
Add the following variables in your global variable declaration.

<variable name="EndpointReference" element="wsa:EndpointReference"/>
<variable name="TargetEndpointLocation" type="xsd:string"/>
Retrieve end-point and assign end-point

<scope name="Scope_GetDynamicEndpoint">
<bpelx:exec name="Java_GetEndPoint"
language="java" version="1.5">
<![CDATA[java.lang.String targetEndpointLocation = null;
targetEndpointLocation =
, "Routing.Target.Default.EndpointURI");
"Endpoint location = '"
+ targetEndpointLocation
+ "' selected from configuration properties.");
catch (oracle.apps.aia.core.config.PropertyNotFoundException e)
"Routing.Target.Default.EndpointLocation not found.");
&& targetEndpointLocation!="")
, targetEndpointLocation);
addAuditTrailEntry("Address set.");
<assign name="AssignPartnerlinkEndpointReference">
<to variable="EndpointReference"/>
<from variable="TargetEndpointLocation"/>
<to variable="EndpointReference"
<from variable="EndpointReference"/>
<to partnerLink="YourParterLinkName"/>

Friday, March 21, 2008

Purging BPEL instances

Here is a script that can be used to purge Oracle ESB instances from the ORAESB schema. I created the script that it can be used by calling a Pl/SQL procedure, to delete instances older than a 'x' days; for a particular bpel process ; version and domain:

REM Name:
REM purge_bpel_dehydration.sql
REM Description:
REM This script purges data from the BPEL dehydration store
REM Usage:
REM purge_bpel_dehydration
REM p_domain DEFAULT '%' - the name of the BPEL domain
REM p_process_name DEFAULT '%' - the name of the BPEL process
REM p_revision DEFAULT '%' - the version of the BPEL process
REM p_older_than DEFAULT 999 - delete instances older than # days
REM p_state DEFAULT -1 - the state of the process
REM Example:
REM sqlplus orabpel/pwd@database
REM exec purge_bpel_dehydration(10);
REM commit;

PROCEDURE purge_bpel_dehydration
p_domain IN VARCHAR2 DEFAULT '%'
, p_process_name IN VARCHAR2 DEFAULT '%'
, p_revision IN VARCHAR2 DEFAULT '%'
, p_older_than IN NUMBER DEFAULT 999
, p_state IN NUMBER DEFAULT -1
b_domain IN VARCHAR2
, b_process_name IN VARCHAR2
, b_revision IN VARCHAR2
, b_older_than IN NUMBER
, b_state1 IN NUMBER
, b_state2 IN NUMBER
cie.cikey cikey
, dmn.domain_id domain_id
, cie.process_id process_id
, cie.revision_tag revision_tag
, cie.modify_date modify_date
, cie.domain_ref domain_ref
, cie.state process_status
cube_instance cie
, domain dmn
WHERE cie.domain_ref = dmn.domain_ref
AND cie.state >= b_state1
AND cie.state <= b_state2
-- the name of the domain
AND dmn.domain_id LIKE b_domain
-- code 5 means completed
AND cie.modify_date < TRUNC(sysdate)-b_older_than
AND cie.process_id LIKE b_process_name
AND cie.revision_tag LIKE b_revision;

l_state1 number;
l_state2 number;
IF p_state = -1
l_state1 := -1;
l_state2 := 999;
l_state1 := p_state;
l_state2 := p_state;
FOR r in c
, p_process_name
, p_revision
, p_older_than
, l_state1
, l_state2
'Purge '||r.process_id||'('||r.revision_tag||')'||
' at '||to_char(r.modify_date, 'YYYY-MM-DD HH24:MI:SS')
delete from wftask wfn where wfn.instanceid = r.cikey;
-- delete invoke calls
-- invoked messages
DELETE FROM invoke_message ime
WHERE ime.domain_ref in
from domain dmn
WHERE dmn.domain_id LIKE p_domain
AND ime.state > 1
AND ime.process_id LIKE p_process_name
AND ime.revision_tag LIKE p_revision
AND ime.receive_date < TRUNC(sysdate)-p_older_than;
-- delete callback calls
DELETE FROM dlv_message dme
WHERE dme.domain_ref IN
from domain dmn
WHERE dmn.domain_id LIKE p_domain
AND dme.state > 1
AND dme.process_id LIKE p_process_name
AND dme.revision_tag LIKE p_revision
AND dme.receive_date < TRUNC(sysdate)-p_older_than;
DBMS_OUTPUT.PUT_LINE ('-> #callback msg '||SQL%ROWCOUNT);


Purging ESB instances

Here is a script that can be used to purge Oracle ESB instances from the ORAESB schema. I created the script that it can be used by calling a Pl/SQL procedure, to delete instances older than a 'x' days:

REM Name:
REM purge_esb_instances.sql
REM Description:
REM This script purges data from the BPEL dehydration store
REM Usage:
REM purge_esb_instances
REM p_older_than DEFAULT 999 - delete instances older than # days
REM Example:
REM sqlplus oraesb/pwd@database
REM exec purge_esb_instances(10);
REM commit;

PROCEDURE purge_esb_instances
p_older_than IN NUMBER DEFAULT '999'
diff NUMBER;
diff := (
(TRUNC(SYSDATE)-p_older_than) - TO_DATE('01/01/1970','MM/DD/YYYY')

where TIMESTAMP < diff


Wednesday, March 12, 2008

Getting started with Oracle SOA, BPEL, ESB, AIA

As I do SOA projects for a few years, many users are just entering this service oriented architecture world. For me the technology is common sense and I expect often that SOA/BPEL/ESB is well known. But off-course this is not the case. When I started working with SOA/BPEL/ESB it was, and still is, a steep learning curve. The Oracle developers world comes from a traditional approach; thinking in functions and entities and since Java came to us, we are even thinking about objects and inherited them.

With SOA it is different, you have to think about processes; functional and technical. The gap between the functional people and technical people is reduced. Processes are part of the business, otherwise they do not have any reason for existence. While processes are running, the can fail, wait on other process, they finish, started, run in parallel etc. So SOA is a mind shift from the traditional development approach point of view.

Last year Oracle announce the Oracle Application Integration Architecture. This is an add-on on the Oracle SOA Suite, which defines an abstract message layer that can be used to interface various systems; Siebel / SAP / Protal BRM / Cordys via a centralized system (Oracle SOA + AIA). This messages layers are created specific for different industries, for example the telecommunication market.

To start with Oracle SOA here are some of useful links:

Oracle SOA Suite general
Oracle SOA Suite software

Oracle Application Integration Architecture
Oracle Blogs
Oracle Forum
Oracle General
Useful tools
Webservice standards