SoapServerURL and SoapCallbackURL Explained in 10.1.3

image Within the BPEL process manager there are two properties that control the URLs used to invoke BPEL instances, the soapServerUrl and the soapCallbackUrl.  In this post I will explore the meaning of these two properties.  These properties become very important when setting up secure environments or HA environments and understanding how they are used is important to any BPEL administrator.

soapCallbackUrl

This is used by the BPEL engine to construct the callback address on an asynchronous interaction.  This is when the BPEL engine will call a service and then expect that service to call it back.  In the request to the service the BPEL engine will provide a callback address so that the service knows where to send the response back to.

This is all done using WS-Addressing as shown in the sample message sent from BPEL below:

<env:Envelope env:encodingStyle=""
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<env:Header>
<ReplyTo xmlns="http://schemas.xmlsoap.org/ws/2003/03/addressing">
<Address>
http://soa.vm.oracle.com:7777/orabpel/default/AsyncEchoClientProcess/1.0/AsyncEchoProcess/AsyncEchoProcessRequester
</Address>
<PortType xmlns:ptns="http://xmlns.oracle.com/AsyncEchoProcess">
ptns:AsyncEchoProcessCallback
</PortType>
<ServiceName xmlns:snns="http://xmlns.oracle.com/AsyncEchoProcess">
snns:AsyncEchoProcessCallbackService
</ServiceName>
</ReplyTo>
<MessageID ans1:rootId="40004"
ans1:parentId="40004"
ans1:priority="0"
xmlns="http://schemas.xmlsoap.org/ws/2003/03/addressing"
xmlns:ans1="http://schemas.oracle.com/bpel">
bpel://localhost/default/AsyncEchoClientProcess~1.0/40004-BpInv0-BpSeq0.3-3
</MessageID>
</env:Header>
<env:Body>

</env:Body>
</env:Envelope>

Note that /env:Envelope/env:Header/ReplyTo/Address is of the form

{soapCallbackUrl}/orabpel/{domainName}/{ProcessName}/{ProcessRevision}/{PartnerLink}/{PartnerLinkRole}

The important bit is that the first part of the ReplyTo Address is formed from the soapCallbackUrl.

Important Point

The hostname in the soapCallbackUrl should be resolvable (can be converted to an IP address) and routable (IP packets can be delivered to it) from any service which is expected to provide an async callback to BPEL.  If this is not the case then the BPEL process must override these values before invoking the service from which it expects a callback.  Note that this may be the address of a front end web server or load balancer and not the address of the BPEL server.

Changing the soapCallbackUrl

The soapCallbackUrl is set by default to the hostname of the machine on which BPEL was installed.  It can be changed by going into the BPEL Admin console (http://hostname:port/BPELAdmin).

Any changes only take effect after a reboot of the BPEL server.

soapServerUrl

This is used by the BPEL engine in a number of different ways.  These are each outlined in the sections below.  Basically the soapServerUrl is used to tell the BPEL server the address at which clients can find it.  This may be the address of the front end web server or load balancer and so is not necessarily the address of the BPEL server.

Important Point

Like the soapCallbackUrl, the hostname in the soapServerUrl should be resolvable (can be converted to an IP address) and routable (IP packets can be delivered to it) from any system which is expected to be a client of BPEL and also from the BPEL server itself.  If this is not the case then the client must override these values before invoking the service.  Note that this may be the address of a front end web server or load balancer and not the address of the BPEL server.

Startup Validation

During startup of the BPEL engine it will try to access {soapServerUrl}/orabpel/xmllib/ws-addressing.xsd to validate that it can access its own address.  Version 10.1.3.5 will still start if it is unable to access this xsd but it will log an error about being unable to access this URL.  This error should be taken seriously as it indicates a problem with your infrastructure.

Setting Endpoint and Imports in WSDL on Deployment

When a BPEL process is deployed the abstract WSDL used to describe the interface to the process is supplemented with binding information to turn it into a concrete WSDL.  In particular the location attribute of the address element is set to {soapServerUrl}/orabpel/{domain}/{process}/{revision}.  This is shown below.

<service name="EchoProcess">
<port name="EchoProcessPort" binding="tns:EchoProcessBinding">
<soap:address location="http://soa.vm.oracle.com:7777/orabpel/default/EchoProcess/1.0"/>
</port>
</service>

Processes deployed before a change to the soapServerUrl property will keep the old location value in their WSDL.  This means that when a client retrieves the WSDL of the process, even if it retrieves the WSDL from the new soapServerUrl it will still be told to call the service at the old soapServerUrl location.

Processes that support asynchronous interactions also have additional message types added to their WSDL to support ws-addressing.  Part of these additions is the inclusion of an import statement that includes the ws-addressing.xsd file.  This file is referenced as an absolute URL so that it is not dependent on the location used to retrieve the WSDL.

<schema xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://schemas.xmlsoap.org/ws/2003/03/addressing"
schemaLocation="http://soa.vm.oracle.com:7777/orabpel/xmllib/ws-addressing.xsd"/>
</schema>

This import URL is of the form {soapServerUrl}/orabpel/xmllib/ws-addressing.xsd, this is the same URL used to validate access to the BPEL server.

Accessing WSDL from Console

When you try to invoke a BPEL process directly from the console using the Initiate tab then the BPEL console constructs the URL to retrieve the WSDL of the process using the soapServerUrl.  If this is incorrect then the initiate tab will throw an error similar the following:

WSDLException: faultCode=PARSER_ERROR:
Failed to read wsdl file at: "{soapServerUrl}/orabpel/default/VacationRequest/1.0/VacationRequest?wsdl",
caused by: java.net.UnknownHostException. : java.net.UnknownHostException: {soapServerUrl hostname}: {soapServerUrl hostname}

This will also cause an error when you try to access the WSDL from the WSDL tab of the process.

If this problem occurs then you need to correct your system so that the soapServerUrl is accessible from the BPEL server machine.

SOAP Optimisation Processing

When invoking a SOAP service the BPEL engine will check if the location of the target service starts with {soapServerUrl}/orabpel.  If it does then it will use an optimised transport, bypassing the HTTP stack and making the call via a Java API instead.  This behaviour can be disabled by setting the optSoapShortcut property on the partner link to be false.

Changing the soapServerUrl

The soapServerUrl is set by default to the hostname of the machine on which BPEL was installed.  It can be changed by going into the BPEL Admin console (http://hostname:port/BPELAdmin).

Any changes only take effect after a reboot of the BPEL server.  The wrinkle to this is that when a process is deployed it stores its WSDL using the current soapServerUrl but the BPEL server serves up the location using the soapServerUrl in effect at the time the BPEL engine was started until the BPEL server is rebooted.  The net effect is that if I change my soapServerUrl and deploy a process I see that it is using the old soapServerUrl, but then I reboot the server and find that the same process is now using the new soapServerUrl.  But BPEL processes deployed when the old soapServerUrl was in effect keep their locations as the old soapServerUrl.

Things to Know

Some important things to know:


  • soapCallbackUrl is separate from soapServerUrl to allow different communication channels for processes that have started from processes that are not yet initiated.
  • Most customers should set soapServerUrl and soapCallbackUrl to be the same value.
  • soapCallbackUrl must be resolvable and routable by services that will callback into the BPEL server, note that this may include BPEL processes or human workflow.
  • soapServerUrl must be resolvable and routable by BPEL server itself and by clients of the BPEL server.
  • Changes to soapServerUrl does not effect existing process endpoints.

I hope this was useful, it seems that I have fielded a number calls about this recently and so felt that some explanation was necessary.

Comments:

Post a Comment:
Comments are closed for this entry.
About

Musings on Fusion Middleware and SOA Picture of Antony Antony works with customers across the US and Canada in implementing SOA and other Fusion Middleware solutions. Antony is the co-author of the SOA Suite 11g Developers Cookbook, the SOA Suite 11g Developers Guide and the SOA Suite Developers Guide.

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