X

Customizing any BPEL Project Artifact using <customizeDocument>

Ramkumar Menon
Director, Product Strategy

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.

Join the discussion

Comments ( 21 )
  • Chintan Shah Tuesday, May 13, 2008
    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
  • Ramkumar Menon Tuesday, May 13, 2008
    Hi Chintan,
    I have replied to the thread mentioned in the original comment
  • Chintan Shah Tuesday, May 13, 2008
    Thanks Ram,
    Really appreciate your help.
    Regards,
    Chintan
  • Amar Misra Wednesday, October 15, 2008
    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
  • Hari Thursday, February 19, 2009
    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.
  • guest Thursday, March 19, 2009
    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
  • Jp Thursday, March 19, 2009
    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
  • Sumit Sarkar Monday, March 30, 2009
    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
  • Evangeline Monday, October 12, 2009
    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
  • Anonymous Wednesday, March 10, 2010
    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.
  • Quebec Nordiques jerseys Thursday, November 18, 2010
    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
  • cipro how to order cheap online Tuesday, April 26, 2011
    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.
  • antique Tuesday, April 26, 2011
    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.
  • Houston Home Loan Tuesday, April 26, 2011
    I really like your writing style, wonderful information, regards for putting up : D.
  • cheap amoxil generics Wednesday, April 27, 2011
    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.
  • Clelia Kerzman Thursday, April 28, 2011
    ?wepromise? Super exciting!!!! We just received our first handbag for the Celebrity Handbag Auction coming up in July and it's
  • crestor no rx Thursday, April 28, 2011
    You gave tremendous positive points there. I did a search on the topic and found most peoples will agree with your blog.
  • cheap jerseys from china Friday, April 29, 2011
    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.
  • cheap jerseys from china Friday, April 29, 2011
    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
  • cheap jerseys from china Friday, April 29, 2011
    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.
  • car scrap Friday, April 29, 2011
    Your blog doesn't load appropriately for me, might want to check into it.
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.