JBoss.orgCommunity Documentation

RiftSaw 2.0.0.Final

User Guide

This is the User Guide for the RiftSaw BPEL process engine.

RiftSaw provides a JBoss AS integration for the Apache ODE BPEL engine. For detailed information on executing BPEL processes within Apache ODE, we would refer the reader to the Apache ODE website and documentation.

In addition to the ability to run the Apache ODE engine within JBoss AS, the RiftSaw project also provides a GWT based administration console, replaces the Axis2 based transport with JBossWS (which can be configured to use Apache CXF), and provides tighter integration with JBossESB.

The BPEL console can be located using the URL: http://localhost:8080/bpel-console.

The first screen that is presented is the login screen:

The default username is admin with password password.

The Access Control mechanism used by the admin console is configured in the $deployFolder/bpel-console/bpel-identity.sar/META-INF/jboss-service.xml. The JAAS login module is initially set to use a property file based access mechanism, but can be replaced to use any appropriate alternative implementation.

The users for the default mechanism are configured in the property file $deployFolder/bpel-console/bpel-identity.sar/bpel-users.properties. The entries in this file represent username=password.

The user roles for the default mechanism are configured in the property file $deployFolder/bpel-console/bpel-identity.sar/bpel-roles.properties. The entries in this file represent username=role. The only role of interest currently is administrator.

The direct deployment approach is demonstrated using an Ant script in each of the quickstart examples. For example,

This excerpt from the Ant build file for the hello_world quickstart example shows that deploying a RiftSaw BPEL process using Ant is very straightforward. The main points of interest are:

This section will explain how to deploy an Eclipse BPEL project to the RiftSaw BPEL engine running in a JBossAS server.

The first step is to create or import the Eclipse BPEL project. In this case we are going to import an existing project from the ${RiftSaw}/samples/quickstart/hello_world folder. This can be achieved by selecting the Import ... menu item associated with the lefthand navigator panel in Eclipse, and then select the General->Existing Projects into Workspace entry and press the Next button.

Then press the Browse button and navigate to the hello_world quickstart folder. Once located, press the Finish button.

Once the project has been imported, you can inspect the contents, such as the BPEL process and WSDL description.

The next step is to create a server configuration for the JBoss AS environment in which the RiftSaw BPEL engine has previously been installed. From the Eclipse Java EE perspective, the Server tab should be visible in the lower region of the Eclipse window. If this view is not present, then go to the Window->Show Views->Servers menu item to open the view explicitly.

In the Servers view, right click and select the New->Server menu item.

Select the appropriate JBoss AS version, and then press Finish.

Before being able to deploy an example, we should start the new server. This can be achieved by right clicking on the server in the Servers tab, and selecting the Start menu item. The output from the server will be displayed in the Console tab.

Once the server has been started, right click on the server entry again, and select the Add and Remove ... menu item.

Select the Quickstart_bpel_hello_world project, press the Add button and the press the Finish button. This will cause the project to be deployed to the server.

Once the project has been deployed, it will show up as an entry below the server in the Servers tab.

The final step is to test the deployed BPEL process. In this example, we can do this using the ant script provided with the quickstart sample. Right click on the build.xml file in the root folder of the project, and select the Run As->Ant Build ... menu item. NOTE: It is important to select the menu item with the "...", as this provides a dialog window to enable you to select which ant target you wish to perform.

Deselect the deploy target, and select the sendhello target, before pressing the Run button. This was send a test 'hello' message to the server, and then display the response in the Console tab.

If you now want to update the BPEL process, select the assignHelloMesg node in the diagram, and select the Properties view. On the left of the view is a vertical list of tabs. Select the Details tab. Then select the "Expression to Variable" from the list, and update the concat function's second parameter - for example to add 'UPDATED' to the text.

Once the update has been saved, go to the Server View and select the Full Publish option from the menu associated with the Quickstart_bpel_hello_world project. This will cause the project to be re-deployed to the RiftSaw server.

The final step is to then re-run the 'sendhello' target within the build.xml file, to send a new request, and view the response. The response should now be modified according to the changes you made in the BPEL process.

If you expand the deployed project node, in the Server View, you will see that both of the deployed versions are shown. The older version is retained as there may still be BPEL process instances using that version of the process. If you right-click on each of the child nodes, you will see that it is also possible to undeploy the specific versions. However, if you explicitly undeploy a version, then any remaining active process instances for that version will be terminated.

You can then use the menu associated with the project, contained in the Server View, to undeploy the project (using the Add and Remove ... menu item) and finally use the menu associated with the server itself to Stop the server.

Apache ODE provides the means to customise certain properties, associated with a BPEL endpoint, by specifying the properties in a file with an extension of .endpoint.

For information on the properties that can be specified in this file, please see the Apache ODE documentation, located at: http://ode.apache.org/endpoint-configuration.html.

This section explains how to deploy these .endpoint files as part of a RiftSaw deployment.

Apache ODE supports two locations for finding these .endpoint files. A 'global' configuration folder, which by default is ode/WEB-INF/conf, and a process deployment specific location, which is ode/WEB-INF/processes/$your_process. Properties associated with the 'global' configuration override any property values provided in the process specific location.

RiftSaw currently does not support a 'global' configuration location, so it will only obtain the configuration files from the deployed BPEL bundle. More specifically, from the root location within the BPEL deployment unit, along side the BPEL deployment descriptor.

So, for example, if you place a file called test.endpoint in the ${RiftSaw}/samples/quickstart/hello_world/bpelContent folder, with the following content:

	# 3 minutes

then once deployed, the helloworld example could wait up to a maximum of 3 minutes to respond. To test this out, edit the hello_world.bpel and insert a wait activity before the response - similar to the following:


This will wait 2 minutes 30 seconds before responding, which is 30 seconds more than the default timeout, but still within the new timeout period specified within the test.endpoint file. If you then wish to try forcing the timeout to occur, simply increase the wait duration to 3 minutes 30 seconds, and resubmit the test message using the ant sendhello command.

By default RiftSaw uses the jUDDI client libraries of JBossESB/SOA-P, and the client configuration is found in the deploy/jbossesb.saw/esb.juddi.client.xml. Both the name of the ClerkManager and the Clerk itself are specified in the bpel.properties file.

Table 4.1. The UDDI related properties in the bpel.properties

attributetype (default)description
bpel.uddi.registrationboolean (true) If set to 'false', the UDDI integration is turned off. The RiftSaw installation process sets this value to 'true' only if the jbossesb-registry.sar is detected containing a jUDDI v3 registry. In all other case it is defaulted to false.
bpel.webservice.secureboolean (false) The UDDI Registration process registers an WSDL AccessPoint in the BindingTemplate for the BPEL Service it is registering. The BPEL server exposes the service WSDL Endpoint on the WS stack (Currently we support JBossWS and CXF), if your WS stack is configured to a use a secure (https) protocol, then you need to switch this setting to 'true'. Note that this setting is used during the registration process only.
bpel.uddi.client.implString (org.jboss.soa.bpel.uddi.UDDIRegistrationImpl) Name of the a class that implements the org.jboss.soa.bpel.runtime.engine.ode.UDDIRegistration interface. The RiftSaw installation process set this value to org.jboss.soa.bpel.uddi300.UDDI300RegistrationImpl if JBossESB-4.7 is detected. JBossESB-4.7 uses the jUDDI-3.0.0 client libary, while SOA-P-5.0.0 and future version of JBossESB will use jUDDI-3.0.1 or higher and for those it is set to org.jboss.soa.bpel.uddi.UDDIRegistrationImpl.
bpel.uddi.clerk.configString (not used by default) Defines the path to the bpel.uddi.client.xml config file. This can be left commented out if you want to use the jbossesb.sar/esb.uddi.client.xml. However in that case a bpel.uddi.clerk.manager needs to be defined.
bpel.uddi.clerk.managerString (esb-registry) Defines the ClerkManager name that will be used if the bpel.uddi.clerk.config is left commented out. This value should correspond to the name of the manager in the esb.juddi.client.xml. For JBossESB-4.7 this is 'test-manager', while for SOA-P-5.0.0 and newer version of JBossESB it is 'esb-registry'. Note that if the bpel.uddi.clerk.config is defined, the setting of the bpel.uddi.clerk.manager is ignored.
bpel.uddi.clerkString (BPEL_clerk) Defines the Clerk name that will be used. This value should correspond to the name of the clerk in the esb.juddi.client.xml. By default this is set to 'BPEL_clerk'.
bpel.uddi.lookupboolean (false) If set to true, the creating process of the partner channel will do a lookup by serviceName in the UDDI, and a WSDL Endpoint is retrieved. This WSDL Endpoint is the then used to obtain the WSDL. This process makes it easier to move Endpoints around within your deployment, without having to update the partnerlink WSDL files in your bpel deployments. Note that an it is still a requirement to deploy the initial partnerlink WSDL file for each partnerLink.

The BPELInvoke ESB action can be used within a jboss-esb.xml to request an invocation on a BPEL process running inside RiftSaw. The only constraints are that RiftSaw is installed within the same Java VM and that the requested BPEL process must have been deployed to the local RiftSaw engine.

The following example illustrates the BPELInvoke ESB action being used as part of the bpel_helloworld sample.

The ESB action class is org.jboss.soa.esb.actions.bpel.BPELInvoke.

The properties for this ESB action are:

This ESB action supports inbound messages with content defined as either:

When the message content represents the complete multipart message, this must be defined as a top level element (whose name is irrelevant) with immediate child elements that represent each of the multiple parts of the message. Each of these elements must then have a single element/node, that represents the value of the named part.

This shows an example of a multipart message structure. The top element (i.e. message) is unimportant. The elements at the next level represent the part names - in this case there is only a single part, with name TestPart. The value of this part is defined as a text node, with value "Hello World". However this could have been an element representing the root node of a more complex XML value.

The following diagram illustrates the inter-relationship of the JBossESB bpel_helloworld quickstart and the RiftSaw BPEL process configuration files.

The normal response from a WSDL operation will be returned from the BPELInvoke ESB action as a normal message and placed on the action pipeline ready for processing by the next ESB action, or alternatively if no further actions have been defined, then returned back to the service client.

Faults, associated with a WSDL operation, are handled slightly differently. Depending on configuration it is possible to receive the fault as an ESB message or for the fault to be treated as an exception which aborts the action pipeline. The configuration property used to determine which behaviour is used is called abortOnFault. The default value for this property is "true". As an example, from the loan fault quickstart sample,

A WSDL fault has two relevant pieces of information, the fault type (or code) and the fault details. These are both returned in specific parts of ESB message's body.