Execute business processes with Eclipse

STP BPMN Modeler, Eclipse ATL, and Apache ODE

Everyone — from consultants and analysts to architects and engineers — has ideas. But implementing a new idea can be challenging, requiring knowledge of an unfamiliar development language or hiring costly developers. What if there was a way to create an executable business process using a graphical editor that can ultimately be executed on an appropriate engine? Well, there is. Using the Eclipse STP BPMN Modeler, you can graphically create a business model represented in XML that can be converted to an executable using Eclipse ATL that will ultimately deploy on Apache ODE.

Share:

Tyler Anderson, Freelance Writer, Backstop Media

Tyler Anderson received his bachelor's degree in computer science in 2004 and his master's degree in electrical and computer engineering in 2005 from Brigham Young University. He worked with Stexar Corp. as a design engineer from May 2005 to August 2006. He was discovered by Backstop Media LLC in early 2005, and has written and coded numerous articles and tutorials for IBM developerWorks.



29 January 2008

Before you start

This tutorial is for those that would like to learn both Business Process Modeling Notation (BPMN) and Business Process Execution Language (BPEL) XML formats using the Eclipse SOA Tools Platform BPMN Modeler to model a business process, convert BPMN to a BPEL-executable deployable to Apache Orchestration Director Engine (ODE). Using these processes and technologies allows you to model business processes you can quickly validate. If BPMN, BPEL, ODE, STP, or other acronyms used in this tutorial are new to you, see Resources for explanations.

About this tutorial

This tutorial shows you how to use the Eclipse SOA Tools Platform (STP) to model business processes, converting the resulting Business Process Modeling Notation (BPMN) file to a Business Process Execution Language (BPEL) with the help of the Eclipse ATLAS Transformation Language (ATL) project, then deploying it to Apache Orchestration Director Engine (ODE).

The process modeled in this tutorial is one where an online Web surfer comes to a Web site to buy toys. The flow of the process continues with a shipping estimator, checking out with a successful order, e-mailing an invoice to the customer, and initiating the shipping process for the toy.

In this tutorial you'll learn how to do the following:

  1. Install Eclipse STP, Eclipse ATL, the BABEL BPMN2BPEL tools, and Apache ODE
  2. Model a business process in Eclipse STP
  3. Transform the Eclipse STP's BPMN format to BABEL's BPMN format
  4. Transform BABEL's BPMN format to BPEL
  5. Create an Apache ODE deployment descriptor
  6. Write Web Service Definition Language (WSDL) for your business process
  7. Prepare the generated BPEL for deployment
  8. Deploy to Apache ODE

System requirements

This tutorial requires several technologies that work together. For instance, Apache ODE requires a Web container like Apache Tomcat. Here's the full list:

Classic Eclipse
Eclipse is the master platform upon which the Eclipse SOA Tools Platform Project (STP) plug-in runs on. Get the latest version of Eclipse Classic: V3.3.1 was used in this tutorial.
Eclipse SOA Tools Platform (STP)
Here, you'll find all the core plug-ins you'll need to develop with the STP. This tutorial uses VI200710300730. Note there are several plug-ins and available different downloads, so be sure to select the one all-in-one package under the SOA Tools Platform All-In-One Packages heading. This package includes all the dependencies listed under the Requirements heading.
Eclipse ATLAS Transformation Language (ATL)
You'll use the Eclipse ATL project to perform a transformation, converting Eclipse STP's BPMN to BABEL BPMN. This tutorial uses the version titled ATL Bundle 2.0 Standard Version, under the heading ATL Ready-To-Use Bundles.
BABEL tools
To convert BABEL BPMN format to BPEL, these helper tools are required. You'll need to download the Java™ binaries (JAR file) under the BPMN2BPEL bullet. You may also find the downloadable examples and source code useful, as well.
Apache Orchestration Director Engine (ODE)
You'll need the Apache ODE to deploy your business process after the dust has settled in your business process development. Download the WAR distribution file. This tutorial uses V1.1.
Apache Tomcat
This tutorial uses Apache Tomcat as the servlet container for Apache ODE. However, there are other possibilities, such as Jetty. Get the core ZIP file. This tutorial uses V5.5.25.
Java technology
All the tools used in this tutorial require Java technology. Java 6 Update 3 was used in this tutorial.
Operating system
You need an operating system capable of running all of the above. We used Windows® when creating this, but you can use a modern version of Mac OS X or Linux®, as well. Adjust locations of files accordingly.

You'll learn more about installing all these tools before you begin using them later. To learn more about other aspects of these tools, see Resources.


Introduction

Business processes are an integral part of a Service-Oriented Architecture (SOA) and are created using standard XML definitions BPMN and BPEL. In this section, you'll learn more about how business processes fit into the SOA model, and about the two business process XML standards (BPMN and BPEL) and their relationship.

Service-Oriented Architecture

An SOA comprises several services that are accessible and can interact with each other over the Internet. SOA is easy to maintain and deploy since it's done one service at a time. Business processes easily fit into this model, having their own service endpoint, as defined by WSDL that can interact and exchange data with other services over the Internet.

In the next two sections, you'll learn about the business-process modeling and execution formats: BPMN and BPEL.

Business Process Modeling Notation

BPMN essentially defines the business process's tasks, entities, and the arcs between them (the flow among tasks) in XML format. BPMN is the language that the models created using the Eclipse STP BPMN Modeler are converted into. Perhaps a graphical representation of a business process would best explain this concept.

Figure 1. Model of a business process
Model of a business process

The image shows a single horizontal flow of a business process cut into three slices, stacked vertically and in order. In Figure 1, the model of a business process was created using the Eclipse STP BPMN Modeler, which you'll use later. You can see where the process starts with the empty circle on the left, with the flow being guided to the right using arrows/arcs, ultimately ending with the empty circle on the right.

BPMN is simply an XML format describing, for example, the model shown in Figure 1. It contains vertices that correspond to nodes and sequenceEdges that correspond to arrows/arcs. Take a look at an example of each in Listing 1.

Listing 1. Sample vertices and sequenceEdges
    <vertices xmi:type="bpmn:Activity" xmi:id="_OioEMZ-jEdyW35YU1b0yXQ" 
	iD="_OioEMJ-jEdyW35YU1b0yXQ" outgoingEdges="_PBxeUZ-jEdyW35YU1b0yXQ" 
incomingEdges="_Pe-XsZ-jEdyW35YU1b0yXQ _PuxHMZ-jEdyW35YU1b0yXQ" name="orderCheck2" 
activityType="GatewayDataBasedExclusive" looping="false"/>
    <sequenceEdges xmi:type="bpmn:SequenceEdge" xmi:id="_r1A1oZ-iEdyW35YU1b0yXQ"
iD="_r1A1oJ-iEdyW35YU1b0yXQ" source="_mxgfgZ-iEdyW35YU1b0yXQ" 
target="_exzeA5-iEdyW35YU1b0yXQ"/>

Vertices are essentially nodes or tasks, shown graphically in Figure 1 as circles, diamonds and squares. In Listing 1, you can see that they have identifiers, as well as a list of outgoing and incoming edges. Identifiers simply give vertices an ID that can be referenced as sources and targets of sequenceEdges (shown in Figure 1 as directional arrows going from vertice to vertice). The important information in each sequenceEdges is the source and target attributes that specify the source vertices and the destination vertices. Please note that this file format is not executable on Apache ODE as it's only the model of a business process, so you'll use the Eclipse ATL project and an open source tool written by BABEL to convert the model into an executable.

Business Process Execution Language

As the name implies, BPEL is executable on process engines like Apache Orchestration Director Engine (ODE).

The difference between BPEL and BPMN is that BPEL is more structured, being an executable language by definition. Instead of vertices and sequenceEdges, a BPEL XML file contains sequences of instructions that include invoking a Web service operation and statements like while loops that can execute a sequence of code again and again if its condition remains true (see the <condition> ... </condition> tags after the opening <while> tag in Listing 2) and if else-if else statements.

In Figure 1 (slice 2) there is one instance where an arc goes backwards. That is how you code a while loop using the BPMN Modeler. There, you'll see the two vertices labeled while1 and while2 that facilitate the correct branching of processes (while1 combines two input edges into a single output edge, and while2 takes one input edge and splits it into two output edges). The condition of the while loop is defined by while_ok, and if it remains true, the shippingEstimator task will be performed again and again. When the same condition is no longer true, execution breaks and goes to the checkout task.

To see how the above model of a while loop is then represented in BPEL, take a peek at Listing 2.

Listing 2. Example while statement in BPEL
    <while>
      <condition>
         getVariableProperty(shippingEstimator_data_in,Message)="true"
      </condition>

      <invoke name="shippingEstimator" 
              partnerLink="mybiz_flow_servicePartnerLink" 
              portType="sns:mybiz_flow_servicePortType" 
              operation="shippingEstimator" 
              inputVariable="shippingEstimator_data_in" 
              outputVariable="shippingEstimator_data_out" />
      
      <assign name="postShipping">
        <copy>
          <from variable="shippingEstimator_data_out" part="Message" />
          <to variable="shippingEstimator_data_in" part="Message"/>
        </copy>
      </assign>
      
    </while>

Here, you can see the while loop model shown in Figure 1 (slice 2) coded in BPEL format, which has the same image of while loops in other programming languages, except this one is defined using XML. You'll see this snippet of code again later, where you'll also learn about more about other BPEL constructs.

Note that the above BPEL is not ready for deployment alone, since it requires a deployment descriptor and WSDL to define the service endpoints for your business process, which you'll also learn to create for an error-free deployment to Apache ODE.

To sum up: BPMN XML defines a graphical model of your business process with nodes and edges, and BPEL defines an executable model of your business process with executable constructs like while loops and if statements, and statements that call operations on existing Web services.

The business process you'll model is a simple flow of adding a toy to a shopping cart. Users will have the option to use a shipping estimator (the while loop you see in Listing 2), check out, and place an order that can be rejected or accepted, with an accepted order sending an invoice to the customer and placing the order in a shipping queue.

Next, you'll install all the required tools so you can quickly dive into the development of your business process.


Quick installation guide

To get moving onto developing your business process, you're going to quickly install each of the tools from the System requirements section here.

Eclipse SOA Tools Platform (STP)
Contains the BPMN Modeler you'll use to model a toy purchasing business process (shown in Figure 1). The output of the BPMN Modeler is a BPMN XML description of the model.
Eclipse ATLAS Transformation Language (ATL)
Transforms XML models from one model to another. You'll use it to convert the BPMN output from the STP to BPMN readable by the BABEL tools.
BABEL tools
This is a Java command-line tool that converts BABEL BPMN to a preliminary BPEL format you'll tidy and provide deployment descriptors and WSDL format later.
Apaches Orchestration Director Engine (ODE) and Tomcat
Apache ODE runs inside Apache Tomcat. Apache ODE is then where you deploy BPEL and accompanying support files on Apache ODE for execution.

Installing Eclipse STP

The Eclipse SOA Tools Platform (STP) is the core tool containing the BPMN Modeler you're going to need to model a business process in this tutorial. Before proceeding with installing the Eclipse STP, you're going to need to grab Classic Eclipse and the Eclipse STP All-In-One..

To install, it's important that you follow these instructions in order:

  • Unzip the Classic Eclipse to your programs directory.
  • Unzip the Eclipse STP All-In-One to your programs directory (If asked, click overwrite all).

Note that unzipping the Eclipse STP file to the same directory as the Classic Eclipse ZIP file overwrites various files in the Classic Eclipse directory, effectively merging the two. Now rename the Eclipse directory STPbpmn_eclipse. In Windows, run STPbpmn_eclipse/eclipse.exe.

Installing Eclipse ATL

The Eclipse ATL project is the tool you're going to use to convert an STP BPMN XML file to a BABEL BPMN XML file. You should already have downloaded one of the ready to go ATL bundles (in Windows, the file is named ATL_Bundle_2.0.0RC2_Windows.zip). Unzip this file to your programs directory, rename the eclipse directory to ATL_eclipse, and presto! Eclipse ATL installation is done.

To start Eclipse ATL in Windows, run ATL_eclipse/eclipse.exe.

Installing the BABEL tools

You'll use the BABEL JAR file you download to convert BABEL BPMN XML to BPEL. You'll activate this tool on the command line, so save it to a directory in your programs directory called babelBPMNtoBPEL.

Installing Apache ODE and Tomcat

Since Apache ODE runs inside Tomcat, you'll install Apache Tomcat first. To install Tomcat, simply move the ZIP file you downloaded (apache-tomcat-5.5.25.zip) from Apache.org to your programs directory. Now unzip it and set CATALINA_HOME as an environment variable (c:\apps\apache-tomcat-5.5.25). To do so in Windows, click Start > Control Panel. Switch to Classic View, then click System. In the window that pops up, click the Advanced tab, and click Environment Variables. Under "User variables for ...," click New and enter in the new environment variable with CATALINA_HOME as the variable name and the path to the Tomcat home directory as the variable value.

Now click OK, click OK again, and one more time, click OK. That should do it for Tomcat.

Installing Apache ODE is simple now. First unzip the file you downloaded (apache-ode-war-1.1.zip) to your programs directory, extract ode.war from within the apache-ode-war-1.1 directory, and copy it to the webapps directory in Tomcat.

Apache ODE and Tomcat are ready to roll. Next, you'll begin using the Eclipse STP BPMN Modeler.


Using the Eclipse STP BPMN Modeler

The STP BPMN Modeler is quite easy to use. You can model just about anything with a simple drag and drop, which is what you'll get to try out in this section. First, you'll learn how to create a BPMN diagram to model visitors purchasing toys on your Web site. Then you'll learn about a few activity types you'll be using in the model. And finally, you'll see how to ultimately model your business process using the BPMN Modeler.

Your first BPMN diagram

Time to start up the Eclipse STP. Because the BPMN Modeler isn't project-based, you're just going to start it off in a generic project.

To create your new project, click File > New > Project. Next, expand the General folder and select Project.

Figure 2. Creating a generic project
Creating a generic project

Click Next and type in a project name, STPbpmn.

Figure 3. Naming your project
Naming your project

You should now see your new project in the Package Explorer pane. Select it and click File > New > Other. Expand the SOA Tools folder and select Bpmn Diagram.

Figure 4. Creating a new BPMN Diagram
Creating a new BPMN Diagram

Click Next and enter a file name in the File name space: mybiz_flow.

Figure 5. Naming your BPMN diagram
Naming your BPMN diagram

Click Finish to create the BPMN diagram. Your project should now be set up as shown below.

Figure 6. Your project window
Your project window

Excellent! Now you're ready to being learning about a few activity types, elements shown in the palette on the right.

Introducing activity types

There are various activity types you can use to model your business process. Here are five you'll be using to model yours. Empty Start, under Start Events.

Figure 7. Empty Start event
Empty Start event

This activity starts the flow process, the empty circle on the left side of Figure 1. Next is a task, as shown below.

Figure 8. Tasks
Tasks

Tasks are commands like invoking a Web service. The next two are a couple gateways that allow a process to split into to different directions, exclusively or in parallel. First is the exclusive data-based gateway.

Figure 9. Exclusive data-based gateway
Exclusive data-based gateway

You'll see more of how this works later. In short, it's used to branch the business process into two paths, one for if the order failed and another if the order was a success. Next is the parallel gateway.

Figure 10. Parallel gateway
Parallel gateway

You can use this gateway to define two tasks that can be executed in parallel, such as sending an invoice to a customer and queuing an order in the shipping department after an order successfully processed. The last activity you'll check out is the Empty End event, an event that terminates the business process.

Figure 11. Empty End event
Empty End event

This is the empty circle on the right side of Figure 1, terminating the business process flow.

Modeling your business process

Now you finally get to model your business process. To begin, click the Empty Start activity and click a spot in the blue flow panel. Then double-click it and label it start.

Figure 12. Labeling the start activity
Labeling the start activity

Click the task activity type, place it to the right of the start circle, double-click it and label it addToyToCart.

Figure 13. Labeling a task
Labeling a task

Next, you'll create a new arc from the start circle to the addToyToCart task. Hover over the right border of the start circle until a dark solid arrow appears to the right of it, as shown in Figure 14. Click on the small square box to the right of the solid arrow and drag it to the addToyToCart task.

Figure 14. Creating a new arc
Creating a new arc

Let go of the mouse button over the addToyToCart task, and a new arc should appear, linking the two together.

Figure 15. A new arc created
A new arc created

There, you've created your first arc. Your business process is coming together. Continue modeling your business process.

Figure 16. Continuing to model the business process
Continuing to model the business process

With the aid of the above figure, you should be able to create a new task, viewCart, and two exclusive data-based gateways that comprise the while loop. Note that you can also label arcs, as shown in the two arcs coming out of the gateway labeled while2. Simply double-click them, type in a desired label, click Enter, then drag the label to where you want it. Continue modeling, as shown below.

Figure 17. Continuing modeling
Continuing modeling

Here you see the checkout and shippingEstimator tasks you can create and hook up as shown. Note that there is an edge going from shippingEstimator back to the gateway labelled while1: This ultimately becomes the while loop you saw in Listing 2. After the checkout task, you see the equivalent of an if-else statement with the gateway labeled orderCheck. If the order failed, flow moves to the orderFailed task, and if successful, you'll move to the parallel gateway labelled orderTasks. Continue modeling the last bit of the business process.

Figure 18. Finalizing the business process model
Finalizing the business process model

Note how the two tasks, emailInvoice and shippingQueue are within the parallel gateways. They will be executed in parallel since their flow does not matter. The parallel flow then meets back up at orderTasks2 and again at orderCheck2, with the business process terminating at an Empty End event.

You can now examine the resulting BPMN corresponding to your diagram by double-clicking the mybiz_flow.bpmn file in your package explorer file. Here, you can see all the vertices and sequenceEdges that describe the business process you just modeled.

Congratulations! You've successfully modeled a business process using the BPMN Modeler. Next, you'll begin the transformations to convert the BPMN to BPEL.

Transforming Eclipse STP's BPMN to BPEL

With BPMN in hand, you're ready to convert it to BPEL. To do so, you're going to employ the help of the Eclipse ATL project and tools from BABEL. This conversion process is necessary so you have an executable (BPEL) to work with before deployment to Apache ODE. The role of Eclipse ATL is to perform a transformation on the BPMN to a BPMN format readable by the BABEL tools, which convert the final BPMN to BPEL. You'll begin by creating your first Eclipse ATL project.

Your first Eclipse ATL project

To create your Eclipse ATL project so you can perform a STP BPMN to BABEL BPMN, you need to create a new project within the Eclipse ATL. Start up the ATL (ATL_project/eclipse.exe). Note there are two pre-existing projects: Families2Persons and Tree2List. You can ignore these or delete them altogether since you won't be using them.

Now you'll create a new project to house the transformation rules you're going to set up. Click File > New > ATL Project.

Figure 19. Creating an ATL project
Creating an ATL project

Next, a window pops up asking for a name. Name the project STPbpmnTObabelBPMN, as shown below, then click Finish.

Figure 20. Naming your ATL project
Naming your ATL project

Your ATL project is now created, but more remains. You need to grab a few files from the tutorial download in the Download section. Once you've got the download, extract three files and copy them to your ATL project.

ATL_project\STPbpmnTObabelBPMN\metamodels\bpmn.ecore
An EMF file defining the structure for BABEL BPMN files.
ATL_project\STPbpmnTObabelBPMN\metamodels\stpmodel.ecore
The EMF file defining the structure for STP BPMN files.
ATL_project\STPbpmnTObabelBPMN\transformation\bpmn2babel.atl
This is an ATL file defining the transformation from STP BPMN to BABEL BPMN.

Also, copy the mybiz_flow.bpmn file generated from your Eclipse STP project to your Eclipse ATL project. Your package explorer for your ATL project should now look like Figure 21.

Figure 21. Package Explorer view for ATL project with files copied over
Package Explorer view for ATL project with files copied over

Note that the bpmn2babel.asm file is auto-generated by Eclipse ATL when it compiles the bpmn2babel.atl file.

At this point, your ATL project is created and you're ready to proceed to the transformation.

Transforming STP BPMN to BABEL BPMN

Now it's time to transform the BPMN output from the Eclipse STP BPMN Modeler to a BPMN format readable by the BABEL tools. Before performing the transformation. However, there is one last thing you need to do. As of the current version of the Eclipse STP, there is a bug in the output of the BPMN (it does not conform to the corresponding stpmodel.ecore). To fix, open up the mybiz_flow.bpmn file by double-clicking it in the package explorer window (see Figure 21).

Replace all instances of the following:

  • Parallel Gateway with GatewayParallel
  • Exclusive Data-based Gateway with GatewayDataBasedExclusive
  • Empty Start Event with EventStartEmpty
  • Empty End Event with EventEndEmpty

The BPMN is ready for transformation. To proceed, click Run > Open Run Dialog. In the left-hand column, right-click ATL Transformation, and click New. Name the launch configuration STPbpmnTObabelBPMN, and in the project pane select your project in the name (STPbpmnTObabelBPMN) and the bpmn2babel.atl file in your project, as shown in Figure 22. Then you can select the BPMN and BABEL Ecore metamodels in the metamodels pane by typing in the path to each Ecore file, or by selecting the appropriate workspace button and browsing for it.

Figure 22. Configuring the ATL launch configuration
Configuring the ATL launch configuration

Then, again shown in Figure 22, you need to choose a source model (mybiz_flow.bpmn) by entering it directly or clicking Workspace and browsing for the right file in your project. Since the target model doesn't exist yet (this is the file that gets generated by Eclipse ATL), you're going to copy the source model file to the target model file, and type BABEL_ as the prefix to it (see the source and target model panes in Figure 22).

Quite a lot of information so far, hunh? And there's just one more thing left to do: add a library. To do so, click Add library (shown in bottom left of Figure 22), a window will pop up asking for the name, accept the default, and just click OK. A library will then appear in the Libraries pane (to the right of the Target Models pane in Figure 22). Click the Workspace button, shown below.

Figure 23. Entering the library file to your ATL launch configuration
Entering the library file to your ATL launch configuration

Browse for the file in your projects transformation directory.

Figure 24. Entering a library
Entering a library

Click OK. Finally! The launch configuration is ready to roll. Make sure to click Apply in the bottom right of the window to save your changes.

To launch to the configuration and perform the transformation, click Run on the bottom right of the window, and voila! You should now notice a new file in the models folder in your ATL project, as shown in Figure 25. This is the BABEL BPMN intermediary format.

Figure 25. Generating BABEL BPMN
Generating BABEL BPMN

Transforming BABEL BPMN to BPEL

To perform the transformation, copy the BABEL_mybiz_flow.bpmn from your Eclipse ATL project to the babelBPMNtoBPEL directory you created earlier when you installed the BABEL tools.

Before proceeding with the remaining transformation, there's one last edit you need to make to the BABEL_mybiz_flow.bpmn file. First: Notice there are two <babelBpmn:DocumentRoot> children elements. Remove one of them (you can compare your file to the one in the babelBPMNtoBPEL directory of the code you downloaded from the Download section).

Open a console, and change your directory to the babelBPMNtoBPEL containing the BPMN2BPEL.jar file and the BABEL BPMN file you just created (BABEL_mybiz_flow.bpmn). Type the following to create BPEL: java -jar BPMN2BPEL.jar BABEL_mybiz_flow.bpmn.

The last few lines from running the above tool creates the following output, as shown in Listing 3, creating a new file, BPEL_BABEL_mybiz_flow.bpmn.bpel.

Listing 3. Transforming from BABEL BPMN to BPEL
328  [main] DEBUG controller.BPMN2BPEL  - Step 5: Build the BPEL-Tree.
328  [main] DEBUG controller.BPMN2BPEL  - Output the BPEL-XML into a File.
343  [main] DEBUG model.backEnd.EmitterBPEL4BPMN  - ChildLIST:1
343  [main] DEBUG controller.BPMN2BPEL  - Directory :
343  [main] DEBUG controller.BPMN2BPEL  - File : 
BPEL_BABEL_mybiz_flow.bpmn.bpel

Rename BPEL_BABEL_mybiz_flow.bpmn.bpel to mybiz_flow.bpel and copy it to another directory: apacheODE_process/mybiz_flow/. Open the BPEL file and notice the while loop, as shown below.

Listing 4. while loop created
    <while condition="while_ok">
      <invoke name="shippingEstimator"
              partnerLink="local" 
              portType="localPT" 
              operation="shippingEstimator" 
              inputVariable="shippingEstimator_data_in" 
              outputVariable="shippingEstimator_data_out" />
    </while>

Here, you can compare the while loop created here to the one you'll end up with in Listing 2. Note that the syntax of the two are different. This is because the auto-generated version creates an excellent starting place for BPEL development, a bonus to creating BPEL from scratch.

In the next section, you'll prepare your business process for deployment on Apache ODE.


Preparing a business process for deployment to Apache ODE

You've got BPEL to work with. You'll use this file as a starting point for the BPEL file you'll ultimately deploy to Apache ODE. Before doing that, however, you'll create an Apache ODE deployment descriptor and two WSDL files: one as the service endpoint for your BPEL and another as a supporting service each to facilitate the functionality of your toy purchasing business process.

Writing a deployment descriptor

The deployment descriptor you're about to write tells Apache ODE how to deploy your toy purchasing business process and what services to activate. Create a new file, deploy.xml, and define it as shown below.

Listing 5. Writing an Apache ODE deployment descriptor
<deploy xmlns="http://www.apache.org/ode/schemas/dd/2007/03"
        xmlns:pns="http://ibm/dw/ode/bpel/executor" 
        xmlns:wns="http://ibm/dw/ode/bpel/executor.wsdl"
        xmlns:sns="http://ibm/dw/ode/bpel/service.wsdl">

  <process name="pns:mybiz_flow">
    <active>true</active>
    <provide partnerLink="mybiz_flowPartnerLink">
      <service name="wns:mybiz_flowService" port="mybiz_flowPort"/>
    </provide>
    <provide partnerLink="mybiz_flow_servicePartnerLink">
      <service name="sns:mybiz_flow_serviceService"
               port="mybiz_flow_servicePort"/>
    </provide>
    <invoke partnerLink="mybiz_flow_servicePartnerLink">
      <service name="sns:mybiz_flow_serviceService"
               port="mybiz_flow_servicePort"/>
    </invoke>
  </process>
</deploy>

There are a few elements of importance here. The first is the process element. Notice that it's named after the name of your BPEL file. This is how it knows which BPEL file it's referencing. Next, there are two provide elements that define partner links that reference service endpoints. The first is the main partner link associated with your BPEL file, and the second is the supporting partner link. You'll see how these two partner links get referenced in the two WSDL files you'll write and later, in the changes you'll make to the BPEL file.

Writing WSDL for your business process

WSDL allows you to expose your toy purchasing business process as a service. Below is a simple WSDL with a single message, operation, binding, service, and partnerLinkType, shown below.

Listing 6. Exposing your business process through WSDL
<?xml version="1.0" encoding="utf-8" ?>
<wsdl:definitions 
   targetNamespace="http://ibm/dw/ode/bpel/executor.wsdl"
   xmlns="http://schemas.xmlsoap.org/wsdl/"
   xmlns:tns="http://ibm/dw/ode/bpel/executor.wsdl"
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:plnk="http://docs.oasis-open.org/wsbpel/2.0/plnktype">
  
  <wsdl:message name="mybiz_flowMessage">
    <wsdl:part name="Message" type="xsd:string"/>
  </wsdl:message>
  
  <wsdl:portType name="mybiz_flowPortType">
    <wsdl:operation name="execute">
      <wsdl:input message="tns:mybiz_flowMessage" name="In"/>
      <wsdl:output message="tns:mybiz_flowMessage" name="Out"/>
    </wsdl:operation>    
  </wsdl:portType>
  
  <wsdl:binding name="mybiz_flowSoapBinding"
                type="tns:mybiz_flowPortType">
    <soap:binding style="rpc" 
                  transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="execute">
      <soap:operation soapAction="" style="rpc"/>
      <wsdl:input>
        <soap:body
           namespace="http://ibm/dw/ode/bpel/executor.wsdl"
           use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body
           namespace="http://ibm/dw/ode/bpel/executor.wsdl" 
           use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>

  <wsdl:service name="mybiz_flowService">
    <wsdl:port name="mybiz_flowPort" binding="tns:mybiz_flowSoapBinding">
      <soap:address
            location="http://localhost:8080/ode/processes/mybiz_flow"/>
    </wsdl:port>
  </wsdl:service>
  
  <plnk:partnerLinkType name="mybiz_flowPartnerLinkType">
    <plnk:role name="executor" portType="tns:mybiz_flowPortType"/>
  </plnk:partnerLinkType>

</wsdl:definitions>

The WSDL is quite simple, having a single message used for both the input and output to the execute operation (defined in the portType element). The single operation is then bound to a portType (in the binding element), bound to a port with the service endpoint defined (in the service element). The execute operation starts off the toy purchasing business process, which you'll see in the next section.

Note the links to your deployment descriptor through the partnerLinkType. The parter link name, service, and port name are referenced in the first partnerLink element in Listing 5. In your BPEL, you'll reference a service and its bound port through the above partnerLinkType.

Writing WSDL to support your business process

To invoke outside Web services, your toy purchasing business process requires partner links. This is why there are two partner links in Listing 5: The second one defines the Web service you'll write in this section, which contains each of the operations for each task in your BPMN. Where the first one is called to activate your business process, this supporting Web service is called by the business process as the flow of the business process is executed. Take a look at the WSDL for it.

Listing 7. Exposing your supporting Web service via WSDL
<?xml version="1.0" encoding="utf-8" ?>
<wsdl:definitions 
   targetNamespace="http://ibm/dw/ode/bpel/service.wsdl"
   xmlns="http://schemas.xmlsoap.org/wsdl/"
   xmlns:tns="http://ibm/dw/ode/bpel/service.wsdl"
   xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:plnk="http://docs.oasis-open.org/wsbpel/2.0/plnktype">

  <wsdl:message name="mybiz_flow_serviceMessage">
    <wsdl:part name="Message" type="xsd:string"/>
  </wsdl:message>
  
  <wsdl:portType name="mybiz_flow_servicePortType">
    <wsdl:operation name="addToyToCart">
      <wsdl:input message="tns:mybiz_flow_serviceMessage" name="In"/>
      <wsdl:output message="tns:mybiz_flow_serviceMessage" name="Out"/>
    </wsdl:operation>    

    <wsdl:operation name="viewCart">
...

    <wsdl:operation name="shippingEstimator">
...

    <wsdl:operation name="checkout">
...

    <wsdl:operation name="orderFailed">
...

    <wsdl:operation name="emailInvoice">
...

    <wsdl:operation name="shippingQueue">
...
  </wsdl:portType>
  
  <wsdl:binding name="mybiz_flow_serviceSoapBinding" 
                type="tns:mybiz_flow_servicePortType">
    <soap:binding style="rpc" 
                  transport="http://schemas.xmlsoap.org/soap/http"/>

    <wsdl:operation name="addToyToCart">
      <soap:operation soapAction="" style="rpc"/>
      <wsdl:input>
        <soap:body
           namespace="http://ibm/dw/ode/bpel/service.wsdl"
           use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body
           namespace="http://ibm/dw/ode/bpel/service.wsdl" 
           use="literal"/>
      </wsdl:output>
    </wsdl:operation>

    <wsdl:operation name="viewCart">
...

    <wsdl:operation name="shippingEstimator">
...

    <wsdl:operation name="checkout">
...

    <wsdl:operation name="orderFailed">
...

    <wsdl:operation name="emailInvoice">
...

    <wsdl:operation name="shippingQueue">
...

  <wsdl:service name="mybiz_flow_serviceService">
    <wsdl:port name="mybiz_flow_servicePort" 
               binding="tns:mybiz_flow_serviceSoapBinding">
      <soap:address 
       location="http://localhost:8080/ode/processes/mybiz_flow_service"/>
    </wsdl:port>
  </wsdl:service>
  
  <plnk:partnerLinkType name="mybiz_flow_servicePartnerLinkType">
    <plnk:role name="service" portType="tns:mybiz_flow_servicePortType"/>
  </plnk:partnerLinkType>

</wsdl:definitions>

Visit the Download section to see the full WSDL definition. Note that there is one operation for each task in the toy purchasing business process you've defined throughout this tutorial. This Web service's operations are (for simplicity) defined exactly like the execute operation in Listing 6, so you won't spend much time on this one. You may wish to expand them and make them do other things, then take in a Message of type xsd:string for their input and output messages, depending on the needs of your business process.

Finalizing the generated BPEL file

The last thing you need to do before you are able to deploy your business process to Apache ODE is to fill out the BPEL file you generated in Listing 3 for the toy purchasing business process. You'll need to redefine the Namespaces and import the two WSDL files you wrote in Listings 6 and 7.

Listing 8. Namespaces and WSDL imports
<?xml version="1.0" encoding="UTF-8"?>
<process name="mybiz_flow"
         targetNamespace="http://ibm/dw/ode/bpel/executor" 
         xmlns="http://docs.oasis-open.org/wsbpel/2.0/process/executable"
         xmlns:tns="http://ibm/dw/ode/bpel/executor"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
         xmlns:test="http://ibm/dw/ode/bpel/executor.wsdl"
         xmlns:sns="http://ibm/dw/ode/bpel/service.wsdl"
         queryLanguage="urn:oasis:names:tc:wsbpel:2.0:sublang:xpath2.0"
         expressionLanguage="urn:oasis:names:tc:wsbpel:2.0:sublang:xpath2.0"
>

  <import location="mybiz_flow.wsdl"
          namespace="http://ibm/dw/ode/bpel/executor.wsdl"
          importType="http://schemas.xmlsoap.org/wsdl/" />

  <import location="mybiz_flow_service.wsdl"
          namespace="http://ibm/dw/ode/bpel/service.wsdl"
          importType="http://schemas.xmlsoap.org/wsdl/" />
...

This sets up the BPEL file so you can correctly call out the partner links, message types, services, and operations defined in each of the WSDL files. In fact, you'll list each of the partner links and variables you'll be using in your business process.

Listing 9. Declaring partner links and variables
...
          namespace="http://ibm/dw/ode/bpel/service.wsdl"
          importType="http://schemas.xmlsoap.org/wsdl/" />
  <!--bpmn2bpel Version 1.0-->
  <partnerLinks>
    <!--List of services participating in this BPEL process-->
    <partnerLink name="mybiz_flowPartnerLink" 
                 partnerLinkType="test:mybiz_flowPartnerLinkType" 
                 myRole="me" />

    <partnerLink name="mybiz_flow_servicePartnerLink"
                 partnerLinkType="sns:mybiz_flow_servicePartnerLinkType"
                 partnerRole="service"
                 initializePartnerRole="yes" />
  </partnerLinks>

  <variables>
    <!--List variables used in this BPEL process-->
    <variable name="toyChosen"
              messageType="test:mybiz_flowMessage"/>
    <variable name="addToyToCart_data_in"
              messageType="sns:mybiz_flow_serviceMessage"/>
    <variable name="addToyToCart_data_out" 
              messageType="sns:mybiz_flow_serviceMessage"/>
    <variable name="viewCart_data_out" 
              messageType="sns:mybiz_flow_serviceMessage"/>
    <variable name="shippingEstimator_data_in" 
              messageType="sns:mybiz_flow_serviceMessage"/>
    <variable name="shippingEstimator_data_out" 
              messageType="sns:mybiz_flow_serviceMessage"/>
    <variable name="checkout_data_out" 
              messageType="sns:mybiz_flow_serviceMessage"/>
    <variable name="orderFailed_data_out" 
              messageType="sns:mybiz_flow_serviceMessage"/>
    <variable name="emailInvoice_data_out" 
              messageType="sns:mybiz_flow_serviceMessage"/>
    <variable name="shippingQueue_data_out" 
              messageType="sns:mybiz_flow_serviceMessage"/>
  </variables>
...

Here, you see the two partner links declared. The first is the main partner link that receives the initial instantiation call (see the receive element in Listing 10), followed by the partner link that defines a service you'll invoke for each of the tasks in your business process. In the course of invoking business processes, variables are needed to copy, store, and read data, and so you can see each of the ones you need to define above enclosed in two variables elements.

You'll see how execution of the business process begins.

Listing 10. Initiating the flow
...
  </variables>
  <sequence name="sequenceComponent_5">
    <receive name="ProcessInstantiation"
             partnerLink="mybiz_flowPartnerLink"
             portType="test:mybiz_flowPortType"
             operation="execute"
             variable="toyChosen"
             createInstance="yes" />

    <assign name="copyToy">
      <copy>
        <from variable="toyChosen" part="Message" />
        <to variable="addToyToCart_data_in" part="Message"/>
      </copy>
    </assign>

    <sequence name="sequenceComponent_0">
      <invoke name="addToyToCart" 
              partnerLink="mybiz_flow_servicePartnerLink" 
              portType="sns:mybiz_flow_servicePortType" 
              operation="addToyToCart" 
              inputVariable="addToyToCart_data_in" 
              outputVariable="addToyToCart_data_out" />
      <invoke name="viewCart" 
              partnerLink="mybiz_flow_servicePartnerLink" 
              portType="sns:mybiz_flow_servicePortType" 
              operation="viewCart" 
              inputVariable="addToyToCart_data_out" 
              outputVariable="viewCart_data_out" />
    </sequence>
...

First, an outside client needs to invoke the execute operation of the mybiz_flow service you defined in the mybiz_flow.wsdl file, starting the flow of the toy purchasing business process. This happens in the receive element shown in Listing 10 with the payload stored in the toyChosen variable. Next, you copy the Message part of the toyChosen variable to the Message part of the addToyToCart_data_in variable (since the two don't share the same type, this copy statement is a required addition), which is the input to the invoking of the addToyToCart operation. The output of the addToyToCart operation is then fed in as the input to the viewCart operation. Note the flow of execution is exactly the same as the toy purchasing business process you've modeled previously (see Figure 1).

Continue filling in your BPEL, as shown below.

Listing 11. The while loop
...
              outputVariable="viewCart_data_out" />
    </sequence>
    <assign name="preShipping">
      <copy>
        <from variable="viewCart_data_out" part="Message" />
        <to variable="shippingEstimator_data_in" part="Message"/>
      </copy>
    </assign>

    <while>
      <condition>
         getVariableProperty(shippingEstimator_data_in,Message)="true"
      </condition>

      <invoke name="shippingEstimator" 
              partnerLink="mybiz_flow_servicePartnerLink"
              portType="sns:mybiz_flow_servicePortType" 
              operation="shippingEstimator" 
              inputVariable="shippingEstimator_data_in" 
              outputVariable="shippingEstimator_data_out" />
      
      <assign name="postShipping">
        <copy>
          <from variable="shippingEstimator_data_out" part="Message" />
          <to variable="shippingEstimator_data_in" part="Message"/>
        </copy>
      </assign>
      
    </while>
...

Upon executing the viewCart operation, the output is copied into the shippingEstimator_data_in variable, used in computing the while condition. If the Message part of the shippingEstimator_data_in variable equals "true," the while loop is executed, executing the shippingEstimator task. Upon calling the shippingEstimator operation, the output is copied back to the shippingEstimator_data_in variable, so the while condition can be re-examined. If the output of the shippingEstimator operation is anything other than "true," the execution proceeds with the checkout task.

Listing 12. Verifying an order for checkout
...
    </while>
    <sequence name="sequenceComponent_3">
      
      <invoke name="checkout" 
              partnerLink="mybiz_flow_servicePartnerLink" 
              portType="sns:mybiz_flow_servicePortType" 
              operation="checkout" 
              inputVariable="shippingEstimator_data_in" 
              outputVariable="checkout_data_out" />
      
      <if>
        <condition>
          getVariableProperty(checkout_data_out,Message)="failed"
        </condition>
        <invoke name="orderFailed" 
                partnerLink="mybiz_flow_servicePartnerLink" 
                portType="sns:mybiz_flow_servicePortType" 
                operation="orderFailed" 
                inputVariable="checkout_data_out" 
                outputVariable="orderFailed_data_out" />
        <else>
          <flow name="flowComponent_1">
            <invoke name="emailInvoice" 
                    partnerLink="mybiz_flow_servicePartnerLink" 
                    portType="sns:mybiz_flow_servicePortType" 
                    operation="emailInvoice" 
                    inputVariable="checkout_data_out" 
                    outputVariable="emailInvoice_data_out" />
            <invoke name="shippingQueue" 
                    partnerLink="mybiz_flow_servicePartnerLink" 
                    portType="sns:mybiz_flow_servicePortType" 
                    operation="shippingQueue" 
                    inputVariable="emailInvoice_data_out" 
                    outputVariable="shippingQueue_data_out" />
          </flow>
        </else>
      </if>  
    </sequence>
    
  </sequence>
</process>

If the output of the call to the checkout operation indicates that the order failed (the Message part of the checkout_data_out variable="failed"), the orderFailed task executes, terminating the business process. If the order was successful (the Message part of the checkout_data_out variable was anything other than "failed"), the emailInvoice and shippingQueue operations are executed in parallel (indicated by the flow element they are enclosed in), terminating the business process.

Your project is ready for deployment to Apache ODE, which is your next task.

Deploying to Apache ODE

You're into the final step where you'll take the two services you defined via WSDL, the executable (BPEL) toy purchasing business process, and deployment descriptor together in a single directory and deploy to Apache ODE. To deploy the business process, start up Apache Tomcat, which automatically activates Apache ODE. Next, copy the directory containing your deployment descriptor, two WSDL files and BPEL (the apacheODE_process\mybiz_flow directory in the tutorial download) to Apache ODE's processes directory: tomcat-5.5.25/webapps/ode/WEB-INF/processes.

You should see the following output in the Tomcat output console, indicating a successful deployment:

INFO - GeronimoLog.info(79) | Deployment of artifact mybiz_flow successful: \
type="inline">[{http://ibm/dw/ode/bpel/executor}mybiz_flow-40]

You can also see the deployed services running on the server by visiting http://localhost:8080/ode/services/listServices (see Figure 26).

Figure 26. Services deployed successfully
Services deployed successfully

You can see the two Web services you exposed via WSDL with all operations found successfully.

You've effectively gone from business process idea to implementation of that idea in a business process deployed on Apache ODE, now an integral part of your overall SOA.


Summary

You've completed the tutorial, with the knowledge to model business processes like the pros. You were also successful at converting the BPMN outputted from the Eclipse STP BPMN Modeler, to BPEL that you were able to prepare and deploy on Apache ODE.

For further extensions of the work initiated here, there is one last hurdle for you to jump: To implement the mybiz_flow_service defined in the WSDL in Listing 7, and there are two ways to do it. First, you can use Axis2 to compile the WSDL into a Java Web services representation (see Resources), or you can manually write another business process to handle each of the invoke elements in your BPEL in succession (see Resources, and the DynPartner example in the Apache ODE download).

Also, be sure to see the Resources for more information on the concepts and technologies introduced in this tutorial.


Download

DescriptionNameSize
Source codeos-eclipse.stpatlode.bpnmtut.source.zip24KB

Resources

Learn

Get products and technologies

Discuss

  • The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
  • The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
  • Participate in developerWorks blogs and get involved in the developerWorks community.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Open source on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Open source
ArticleID=283842
ArticleTitle=Execute business processes with Eclipse
publish-date=01292008