Monitoring SOAP Messages between BPEL Processes

When debugging BPEL processes it can sometime be very useful to see the actual messages flowing between processes. Now, often the audit trail in the BPEL Console provides sufficient information to see whats going on, and by clicking on the appropriate invoke, receive or reply activity you can see the content of the payload that was sent or received. However this is only half the story as it doesn’t show details of the actual soap message exchanged and in particular details such as the SOAP headers used for WS-Security and WS-Addressing. Now you may know that Oracle BPEL PM ships obtunnel a tool for monitoring SOAP Messages exchanged between two parties, e.g. between BPEL and an external web service. For those who aren’t familiar with obtunnel, it’s a TCP Monitor which works by listening on one port and then forwarding the message onto another (i.e. where the actual service is located). The simplest way to configure a process to call a web service via obtunnel is to set the property location on the Partnerlink and re-deploy the process. The value specified here will override the webservice endpoint specified in the wsdl document. This works fine for indivdual service invocations. However if we want to monitor messages between several different BPEL processes, then having to modify multiple partner links across multiple processes can be quite tedious and also requires you to go back and amend them all to there correct value. In addition for asynchronous processes it’s more complicated, since the invoking process will pass a call back location to the invoked process, which as a result causes replies to by-passes obtunnel, so you don’t see the responses coming back. Ideally what we want is a simple way to configure BPEL PM to always go via obtunnel when calling a BPEL process without the need to make any changes to the process definition. This is the subject of this technical note. Configuring the BPEL Server to use obtunnel as a Proxy Oracle BPEL PM can easily be configured to use a proxy; typically this is for such scenrios as placing an HTTP Gateway in front of a BPEL Server. However we can use the same approach to set up obtunnel as the proxy. To achieve this we need to set two properties; soapServerUrl and soapCallbackUrl in the server configuration file. soapServerUrl This URL is published as part of the SOAP address of a process in the WSDL file. The hostname and port for this URL should be customized to match the Host and the Listen Port of your instance of obtunnel. Assuming you are running obtunnel on the same host as your BPEL Server, you just need to change the port number. soapCallbackUrl This URL is sent by the process (using WS-Addressing) as part of the asynchronous callback address to tell the recipient of the request where to send the response to. Again the hostname and port for this URL should be customized to match the hostname and listen port of your instance of obtunnel; so should have the same value as soapServerUrl. The simplest way to set these properties is on the configuration tab from BPEL Admin (to access this on the BPEL Console login screen select goto BPEL Admin). Once set you will need to restart your BPEL Server. Note: You will need to re-deploy any processes currently deployed to your server in order for them to be re-compiled (e.g. generate WSDL) with the correct addresses. Configuring the BPEL Domain Once we have configured the server, any external caller of a process will now access both the WSDL and the service via the proxy URL. However the default behaviour for a process is to by-pass this proxy, why? Well really for reasons of performance; it simply doesn’t make sense for a process to call another process via SOAP as the overhead would be to big, rather a process simply calls another process via a direct in memory Java call which is far more performant. However for our purpose, we can turn this off by setting the property optSoapShortcut to false. The simplest way to set this is in the BPEL Console, click on Manage BPEL Domain (top right hand corner), and then update the property in the configuration tab. Note: In version 10.1.3.0.1, this property is not actually specified in the domain configuration file, so you will need to add it manually to the domin config file, located at: [bpel_home]/domains/[domain]/config/domain.xml Once added you will need to re-start the engine for it to pick up the change (from then on you can modify it as normal in the domain configuration tab). Running obtunnel The simplest way to run obtunnel, is to launch the BPEL Developer Prompt, this simply launches a Command Prompt with all the appropriate environment varaiables set. From here simply type the command obtunnel. Once launched simply specify the port you want to listen on, and then the host name and port of your BPEL Server. Summary Using this approach you can easily monitor the various SOAP messages between processes, without the need to make any actual changes to the configuration of the process. All that is required is to deploy them to a version of the BPEL PM Server configured to use the proxy. Note: If you develop your BPEL Processes against the “Proxy BPEL PM Server”, then the WSDL locations in the PartnerLinks will contain the Host and Port No of the Proxy of the service. This is typically not a problem as you re-configure these as part of the process of deploying the processes to a test / production BPEL PM Server.