Customizing any BPEL Project Artifact using <customizeDocument>

Tokenization of artifacts in a BPEL Project


This note describes a simple ant task that I had come up with that provides an easy and flexible method to enable migration of Process artifacts while deploying to multiple target environments.


Problem Statement


Most often, the BPEL process projects that you develop contain XSDs and WSDLs that fall into one or more of the following categories.
a) The artifacts themselves are hosted on a dedicated server for the specific environment. [For instance, in the OHS htdocs within the development server] The artifacts are referred from the project using absolute URLs, containing the host, port, and other server specific information.
b) The artifacts include or import other artifacts that are hosted on a dedicated server for the specific environment.
c) The WSDL contains a JNDI location that changes for each environment.
d) The WSDL defines inline schemas that contain imported remote XSDs that again are hosted on the dedicated development server.
If your process exhibits one or more of the above characteristics, then more often that not, you will encounter the challenge of automating the migration of these artifacts at deployment time, especially when you have a medium to large number of projects, and/or if you have multiple target environments to deploy to.
There are multiple approaches that are in prevelance today to tackle this.
a) The laborious error-prone way of manually replacing the URLs/JNDI names for the new environments.
b) Usage of &lt;customize> and &lt;customizeWSDL> ant tasks.


But what will be really useful is a generic customization infrastructure that enables users to tokenize any arbitrary XML based artifact within the BPEL Project that includes, but is not limited to
a) The BPEL file
b) The WSDL file(s)
c) XSDs
d) XSLT
e) Toplink Mappings
The list goes on.


Overview


The above issues are addressed through a new customization ant task, namely customizeDocument. This task is very similar in usage and behaviour to the existing customization tasks shipped with the product.
The task allows token replacements of contents of any element or attribute that can be reached through an XPath expression. The only limitation of the task is within the tokenization of Processing Instructions within your XML based documents. For instance, the Jdeveloper generated XSL Map file contains a PI indicating the URLs of the source and target XSDs for the map. These URLs cannot be tokenized using this task, nor is this supported through any of the existing customization task.



Setup and Usage


To setup this task, perform the following steps.
a) Copy the customtasks.jar available at http://blogs.oracle.com/ramkumarMenon/gems/customtasks.jar into $ORACLE_HOME\integration\lib directory.
b) Open up ant-orabpel.xml in $ORACLE_HOME\bpel\utilities directory and paste the following piece of code into the file within the &lt;project> element.



&lt;path id="custom.tasks.class.path">
    &lt;pathelement location="&lt;absolute path to location of customtasks.jar>"/>
 &lt;/path>
 
  &lt;property name="custom.tasks.class.path" refid="custom.tasks.class.path"/>


&lt;taskdef name="customizeDocument" classname="com.collaxa.cube.ant.taskdefs.customize.document.CustomizeDocument">
    &lt;classpath>
      &lt;pathelement path="${custom.tasks.class.path}"/>
    &lt;/classpath>
&lt;/taskdef> 


The usage of this task is best illustrated through a simple running example.


You have a BPEL process project named �CreatePurchaseOrder� that you have deployed to the �test� environment. After you have performed all the necessary tests, you wish to promote this process to the production environment.
The project contains amongst others, the process WSDL named CreatePurchaseOrderService.wsdl that imports the local Process Schema named PurchaseOrder.xsd.


The WSDL also imports another WSDL named GeneralPOHeader.wsdl that is a shared WSDL amongst multiple BPEL Processes. This WSDL is hosted on the OHS on the �test� environment. The CreatePurchaseOrderService.wsdl also imports an XSD named Addressing.xsd that is again hosted on the OHS on the test environment.
Moreover, each environment is associated with a specific support group � that receives notification on faults and errors within processes deployed to that specific environment. The support team email is specified as a preference witihn the deployment descriptor of the BPEL process. [bpel.xml].


This is how a portion of CreatePurchaseOrderService.wsdl looks like.


&lt;?xml version = '1.0' encoding = 'UTF-8'?>
&lt;definitions name="PurchaseOrderService" targetNamespace="http://xmlns.oracle.com/PurchaseOrderService" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:client="http://xmlns.oracle.com/PurchaseOrderService" xmlns:plnk="http://schemas.xmlsoap.org/ws/2003/05/partner-link/">


        &lt;import namespace="http://xmlns.po.com/general" location="http://testsoa.server.com:7780/services/GeneralPOHeader.wsdl" />


        &lt;types>
  &lt;schema xmlns="http://www.w3.org/2001/XMLSchema">
   &lt;import namespace="http://xmlns.oracle.com/CreatePurchaseOrderService" schemaLocation="CreatePurchaseOrder.xsd"/>
   &lt;import namespace="http://xmlns.po.com/addressing" schemaLocation="http://testsoa.server.com:7780/schemas/Addressing.xsd"/>
  &lt;/schema>
 &lt;/types>


         . . . . .       
&lt;/definitions>


And the following is a snippet of bpel.xml.


&lt;?xml version = '1.0' encoding = 'UTF-8'?>
&lt;BPELSuitcase>
   &lt;BPELProcess id="CreatePurchaseOrderService" src="CreatePurchaseOrderService.bpel">
      &lt;partnerLinkBindings>
         &lt;partnerLinkBinding name="client">
            &lt;property name="wsdlLocation">CreatePurchaseOrderService.wsdl&lt;/property>
         &lt;/partnerLinkBinding>
      &lt;/partnerLinkBindings>
      &lt;preferences>
         &lt;property name="supportEmail" encryption="plaintext">test_support_group@clientcompany.com&lt;/property>
      &lt;/preferences>
   &lt;/BPELProcess>
&lt;/BPELSuitcase>


Note the lines highlighted in blue. The intent is to migrate these URLs and preferences to the values applicable for production. The corresponding values in the prod environment are
a) http://prodsoa.server.com:9876/services/GeneralPOHeader.wsdl
b) http://prodsoa.server.com:9876/schemas/Addressing.xsd
c) prod_support_group@clientcompany.com


Note: Steps 1 through 3 are only one of the different ways to manage multiple environments. You could have alternative mechanisms to manage multi-server deployments.


Step 1: Define multiple copies of ant-orabpel.properties, one for each environment - lets say as ant-orabpel_dev.properties, ant-orabpel_test.properties and ant-orabpel_prod.properties. Specify env specific parameters in each of these files.
Step 2: Define the following properties in the ant-orabpel_test.properties.
a) service_host=testsoa.server.com
b) service_ port = 7780
c) support_group_email=test_support_group@clientcompany.com
Define the following properties in the ant-orabpel_prod.properties.
a) service_ host=prodsoa.server.com
b) service_ port = 9876
c) support_group_email=prod_support_group@clientcompany.com
Step 3: Open the build.xml. Change the following line within it.
             &lt;property file="${bpel.home}/utilities/ant-orabpel.properties"/>
             So that it looks like this.
             &lt;property file="${bpel.home}/utilities/ant-orabpel_${deploy_env}.properties"/>
This enables us to pass in a command line argument named deploy_env to the build script and have it import the appropriate ant-orabpel.properties.
For e.g., When you invoke the build for the test environment by typing in ant �Ddeploy_env=test, the build.xml automatically imports the ant-orabpel_test.properties.


Step 4: Open up the compile target block. We will now define the customizations on the process WSDL and the bpel.xml.


&lt;target name="compile">
        &lt;bpelc input="${process.dir}/bpel/bpel.xml" out="${process.dir}/output"
               rev="${rev}" home="${bpel.home}">
        &lt;/bpelc>
    &lt;/target>


Before the bpelc node, add the customizeDocument task.


&lt;target name=�compile�>
   &lt;customizeDocument inFile=�${process.dir}/bpel/CreatePurchaseOrderService.wsdl� outFile=�${process.dir}/bpel/CreatePurchaseOrderService.wsdl�>
&lt;/customizeDocument>
   . . . .
&lt;/target>
The above step indicates the intent to customize the CreatePurchaseOrderService.wsdl.
Next, we need to add the nested �setTextContent� task that allows us to set the text of any attribute or element within the WSDL. Use the setTextContent task to specify the element or attribute to be updated, together with the value that it should be updated with.


&lt;target name=�compile�>
   &lt;customizeDocument inFile=�${process.dir}/bpel/CreatePurchaseOrderService.wsdl� outFile=�${process.dir}/bpel/CreatePurchaseOrderService.wsdl�>
   &lt;setTextContent select=�/wsdl:definitions/wsdl:import/@location� textContent=�http://${service_host}:${service_port}/services/GeneralPOHeader.wsdl�/>
&lt;/customizeDocument>
   . . . .
&lt;/target>


The �select� attribute on the customizeDocument indicates a qualified XPath expression that points to the node within the process WSDL that needs to be customized. In this example, it points to the location attribute of the WSDL import. The �textContent� attribute will hold the text that will be set within the node. In this example, it points to the absolute URL of the imported WSDL. You can also specify the tokens in the URL � The build script will automatically subsitute them with the actual values when it is executed. For instance, if the build were executed with the �Ddeploy_env=test or prod, the appropriate values of service_host and service_port will be substituted from the ant-orabpel_test/prod.properties.


Next, we shall customize the XSD import within the WSDL. For this, add one more setTextContent task within the customizeDocument task. The semantics of this is identical to the earlier step.


&lt;target name=�compile�>
   &lt;customizeDocument inFile=�${process.dir}/bpel/CreatePurchaseOrderService.wsdl� outFile=�${process.dir}/bpel/CreatePurchaseOrderService.wsdl�>
   &lt;setTextContent select=�/wsdl:definitions/wsdl:import/@location� textContent=�http://${service_host}:${service_port}/services/GeneralPOHeader.wsdl�/>
   &lt;setTextContent select=�/wsdl:definitions/wsdl:types/xsd:schema/xsd:import/@schemaLocation� textContent=�http://${service_host}:${service_port}/schemas/Addressing.xsd�/>
&lt;/customizeDocument>


   . . . .
&lt;/target>


The definition of the customization for the WSDL and XSD is almost complete. The missing step is the namespace URI mappings for the prefixes used within the select expressions. In this case, there are two prefixes that need to be mapped to a namespace URI.
a) The �xsd� namespace prefix
b)  The �wsdl� namespace prefix.
These prefixes are declared as properties within the same build file.
Declare two properties, one for each of the namespace URI, as below at the global level within the build.xml [i.e. as a child element of the &lt;project> element. The name of the properties should be  �prefix.� Followed by the actual prefix. The value attribute contains the namespace URI for the prefix.


    &lt;property name="prefix.wsdl" value="http://schemas.xmlsoap.org/wsdl/"/>
    &lt;property name="prefix.xsd" value="http://www.w3.org/2001/XMLSchema"/>



Next, we specify the customization required for the bpel.xml.
Add another &lt;customizeDocument> task within the compile block. We need to add another one since we are customizing a different document.


&lt;project   �..>
     . . . . .
     &lt;property name="prefix.wsdl" value="http://schemas.xmlsoap.org/wsdl/"/>
     &lt;property name="prefix.xsd" value="http://www.w3.org/2001/XMLSchema"/>


     &lt;target name=�compile�>
       &lt;customizeDocument inFile=�${process.dir}/bpel/CreatePurchaseOrderService.wsdl� outFile=�${process.dir}/bpel/CreatePurchaseOrderService.wsdl�>
      &lt;setTextContent select=�/wsdl:definitions/wsdl:import/@location� textContent=�http://${service_host}:${service_port}/services/GeneralPOHeader.wsdl�/>
     &lt;setTextContent select=�/wsdl:definitions/wsdl:types/xsd:schema/xsd:import/@schemaLocation� textContent=�http://${service_host}:${service_port}/schemas/Addressing.xsd�/>
&lt;/customizeDocument>


   &lt;customizeDocument inFile=�${process.dir}/bpel/bpel.xml� outFile=�${process.dir}/bpel/bpel.xml�>
     &lt;setTextContent select=�/BPELSuitcase/BPELProcess/preferences/property[@name=�supportEmail
�]� textContent=�${support_group_email}�/>
&lt;/customizeDocument>
   . . . .
&lt;/target>


Note that the select expression used for this customization does not need any namespace prefixes. This is attributed to the fact that bpel.xml by itself is an unqualified document.


This completes the customization features provided by this task.


Note that the customizeDocument task can be used to customize any bpel process project artifact, although not illustrated in this document.

Comments:

Hello Ram, CustomizeDocument seem to be the way to go, to get rid of all product related issue. Although, I am just trying to find if there is something really missing in CustomizeWSDL usage. Your insight will be greatly appreciated. http://forums.oracle.com/forums/thread.jspa?threadID=655208&tstart=0 Thank you, Chintan

Posted by Chintan Shah on May 13, 2008 at 07:44 AM PDT #

Hi Chintan, I have replied to the thread mentioned in the original comment

Posted by Ramkumar Menon on May 13, 2008 at 10:59 AM PDT #

Thanks Ram, Really appreciate your help. Regards, Chintan

Posted by Chintan Shah on May 13, 2008 at 01:57 PM PDT #

Hi Ram, Many thanks for your post on the customtasks.jar , this has helped us in resolving code issues, however I need to understand the following Is this customtasks.jar an Open Source Code? Does it have any IPR(Intellectual Properiety Rights) issues ? Can this be submitted as a part of Code Delivery to customer ? Can you please let me know any other link (preferably Oracle /SUN Link) from where this jar can be downloaded. In case you need to discuss anything , please give me call my contact details are mentioned below. Thanks and Regards Amar 0091-9903396732

Posted by Amar Misra on October 14, 2008 at 07:38 PM PDT #

Hi Ram, i have a proublem with Ant Scripts . I Create a "IClickSystemESB" process that will define different systems for the project. and Create "IClickServiceGroupESB" process This will define different service groups under the systems for the project. and then Create a TestSysServiceESB process This process should use the system/servicegroups. During deployment of TestSysServiceESB the build file should be able to change the system /service groups to which the process is attached. Anyone can help me.

Posted by Hari on February 18, 2009 at 08:41 PM PST #

Steps I do 1. Loop through list of BPEL Projects 2. Check out the Project from SVN to local 3. Use Ant customizeDocument to modify the WSDL and bpel.xml 4. Deploy to an environment 5. Delete the project from local The issue is Ant is not releasing the control over the modified files in the project, So i am not able to delete the files extracted to my local. When my process exists, i can manually delete the file but not while its running. Please let me know if you have any solution. Thanks, Jayaprakash

Posted by guest on March 19, 2009 at 12:05 AM PDT #

Steps I do 1. Loop through list of BPEL Projects 2. Check out the Project from SVN to local 3. Use Ant customizeDocument to modify the WSDL and bpel.xml 4. Deploy to an environment 5. Delete the project from local The issue is Ant is not releasing the control over the modified files in the project, So i am not able to delete the files extracted to my local. When my process exists, i can manually delete the file but not while its running. Please let me know if you have any solution. Thanks, Jayaprakash

Posted by Jp on March 19, 2009 at 12:07 AM PDT #

Hi Ram, Is there any limitation for the number of setTextContent in a customizeDocument tag? We are facing arrayOutOfBound error when we are using more that 3 setTextContent in a customizeDocument tag. Regards, Sumit

Posted by Sumit Sarkar on March 30, 2009 at 12:39 AM PDT #

Hi I am trying to use customizeDocument for my wsdl. But I am getting the error No node is found with xpath "/wsdl:definitions/wsdl:import/@location" I want to do is there anything I should do specifically in the wsdl ? Thanks Evangeline

Posted by Evangeline on October 12, 2009 at 04:48 AM PDT #

Hello Ram I am trying to use customizeDocument ant task from oracle soa suite ../bpel/lib/customtasks.jar. I am trying to replace res-ref-name in weblogic.xml before deploying. But while building the application it throws java.net.ConnectException: Connection refused exception. Does anybody know what its trying to connect? Any docs for these custom tasks would be greatly appreciated. I have posted this on oracle soa suite forums @ http://forums.oracle.com/forums/thread.jspa?threadID=1041769&tstart=0 Thanks in advance.

Posted by Anonymous on March 10, 2010 at 01:15 PM PST #

I cant believe the NHL is going to risk losing one of the best players in his prime to the nHLwholesale cheap nhl nfl jerseys

Posted by Quebec Nordiques jerseys on November 17, 2010 at 06:44 PM PST #

I feel like you could probably teach a class on how to make a great blog. This is fantastic! I have to say, what really got me was your design. You certainly know how to make your blog more than just a rant about an issue. Youve made it possible for people to connect. Good for you, because not that many people know what theyre doing.

Posted by cipro how to order cheap online on April 26, 2011 at 02:24 AM PDT #

Zune and iPod: Most people compare the Zune to the Touch, but after seeing how slim and surprisingly small and light it is, I consider it to be a rather unique hybrid that combines qualities of both the Touch and the Nano. It's very colorful and lovely OLED screen is slightly smaller than the touch screen, but the player itself feels quite a bit smaller and lighter. It weighs about 2/3 as much, and is noticeably smaller in width and height, while being just a hair thicker.

Posted by antique on April 26, 2011 at 02:35 AM PDT #

I really like your writing style, wonderful information, regards for putting up : D.

Posted by Houston Home Loan on April 26, 2011 at 10:59 AM PDT #

Hands down, Apple's app store wins by a mile. It's a huge selection of all sorts of apps vs a rather sad selection of a handful for Zune. Microsoft has plans, especially in the realm of games, but I'm not sure I'd want to bet on the future if this aspect is important to you. The iPod is a much better choice in that case.

Posted by cheap amoxil generics on April 27, 2011 at 11:46 AM PDT #

?wepromise? Super exciting!!!! We just received our first handbag for the Celebrity Handbag Auction coming up in July and it's

Posted by Clelia Kerzman on April 27, 2011 at 08:00 PM PDT #

You gave tremendous positive points there. I did a search on the topic and found most peoples will agree with your blog.

Posted by crestor no rx on April 28, 2011 at 10:45 AM PDT #

Heya i am for the first time here. I found this board and I find It truly useful & it helped me out a lot. I hope to give something back and aid others like you helped me.

Posted by cheap jerseys from china on April 29, 2011 at 01:25 AM PDT #

I think this is one of the most significant information for me. And i'm glad reading your article. But should remark on some general things, The site style is perfect, the articles is really excellent : D. Good job, cheers

Posted by cheap jerseys from china on April 29, 2011 at 01:30 AM PDT #

I have read a few good stuff here. Definitely worth bookmarking for revisiting. I wonder how much effort you put to make such a excellent informative website.

Posted by cheap jerseys from china on April 29, 2011 at 01:37 AM PDT #

Your blog doesn't load appropriately for me, might want to check into it.

Posted by car scrap on April 29, 2011 at 03:38 AM PDT #

Post a Comment:
  • HTML Syntax: NOT allowed
About

Principal Product Manager

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today