Skip Headers
Oracle® BPEL Process Manager Developer's Guide
10g Release 2 (10.1.2)
B14448-02
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

3 Building a Simple BPEL Process

In this chapter, you create, build, deploy, and test a simple BPEL process: a synchronous Hello World application. It accepts a name as an input message and returns the message Hello followed by the name through a synchronous reply. You design the process in Eclipse BPEL Designer, but alternatively, you can use JDeveloper BPEL Designer, which provides similar functionality.

This chapter contains the following topics:

3.1 Overview of Building a Simple BPEL Process

The Hello World application is familiar to anyone who has taken an introductory programming class. Here it is given as an example of a BPEL process that accepts input, manipulates the input, and returns an output through a synchronous reply.

The BPEL process you create uses the following components:

Figure 3-1 provides an overview of how the Hello World process works.

Figure 3-1 The Hello World BPEL Process

Description of Figure 3-1  follows
Description of "Figure 3-1 The Hello World BPEL Process"

The following actions take place:

  1. The Hello World BPEL process accepts the input from the WSDL client partner link by using a receive activity.

  2. The receive activity repackages the input into a variable.

  3. The Hello World BPEL process adds the greeting using an assign activity, and then sends the result back to the client application through the partner link as output by using the reply activity.


See Also:

  • See "Reviewing the BPEL Source Code" for more information on these activities

  • C:\orabpel\samples\tutorials\101.HelloWorld (for Eclipse BPEL Designer)

  • Oracle_Home\integration\orabpel\samples\tutorials\101.HelloWorld (for JDeveloper BPEL Designer)


3.2 Creating a New BPEL Project Using Eclipse BPEL Designer

You can use the New Project wizard in Eclipse BPEL Designer to generate automatically the skeleton of a BPEL project. This skeleton contains the BPEL source, a WSDL interface, a BPEL deployment descriptor, and an Ant script for compiling and deploying the BPEL process.

To create a new BPEL project:

  1. Open Eclipse BPEL Designer by selecting Start, then All Programs, then Oracle - Oracle_Home, then Oracle BPEL Process Manager version_number, and then BPEL Designer.

  2. Start the BPEL Server by selecting Start, then All Programs, then Oracle - Oracle_Home, then Oracle BPEL Process Manager version_number, and then Start BPEL Server.

  3. From the File menu, click New, then Project.

  4. Select Oracle BPEL Project.

  5. Click Next.

    Description of hello1.gif follows
    Description of the illustration hello1.gif

  6. Enter SyncHelloWorld as the BPEL process name.

    Do not create a project name that begins with a number.

  7. (Optional) Enter http://tutorial.oracle.com as the namespace (replacing the one provided by default).

  8. Change the template to Synchronous BPEL Process.

  9. Leave the Use default check box selected, and click Finish.

    Description of hello2.gif follows
    Description of the illustration hello2.gif

3.3 Browsing a New Project

The New Project wizard creates an initial set of project files for a new synchronous BPEL process, with all the necessary source files. Figure 3-2 provides an overview of how a new project appears in Eclipse BPEL Designer.

Figure 3-2 A New BPEL Process

Description of Figure 3-2  follows
Description of "Figure 3-2 A New BPEL Process"

Table 3-1 describes the initial project files that are created:

Table 3-1 BPEL Process Files

File Description

.project

Eclipse BPEL Designer format project file.

bpel.xml

The deployment descriptor for the process. This file defines the locations of the WSDL files for services this process flow calls, along with other project-specific parameters.

See Also: Appendix E, "Deployment Descriptor Properties"

build.xml

Apache Ant script for compiling and deploying this process.

SyncHelloWorld.bpel

The BPEL source code for the process. The New Project wizard creates an empty flow, with just the minimum activities and definitions for the selected flow type. For a synchronous BPEL process, the only activities are a receive activity to initiate the flow from a synchronous client request, and a reply activity to return the output.

SyncHelloWorld.wsdl

The WSDL (client) interface for this process. This file defines the input and output messages for this flow, the client interface and operations supported, and the BPEL partnerLinkTypes, so the flow can be incorporated into other processes. The New Project wizard generates a document-literal style WSDL that takes a string input message and returns a string response message.


3.4 Viewing the WSDL Interface of a BPEL Process

After you create a new BPEL process, you can view and, if necessary, edit its WSDL file. WSDL files define the interface to the process flow, messages that it accepts and returns, operations that are supported, and so on. You can edit the WSDL file for the BPEL process in text mode in Eclipse BPEL Designer or in any other text editor. If you edit the WSDL file, you must refresh the client interface for the flow, if it is currently open in Eclipse BPEL Designer. In this tutorial, you do not edit the WSDL file; you only view it.

To view the input and output messages of the BPEL process:

  1. In the Navigator, expand SyncHelloWorld and double-click the SyncHelloWorld.wsdl file.

  2. Scroll through the WSDL file.

    The New Project wizard created the SyncHelloWorldRequest complexType element, which the flow accepts as input (in a document-literal style WSDL message), and a SyncHelloWorldResponse element that it returns.

    Description of hello4.gif follows
    Description of the illustration hello4.gif

  3. Close the (unmodified) SyncHelloWorld.wsdl window in the designer by clicking its Close button on the SyncHelloWorld.wsdl tab.

3.5 Switching Between the Overview, Process Map, and Source Code

This section describes how to view the BPEL file in three different ways.

3.5.1 Viewing an Overview of a BPEL Process

To display a visual overview of a BPEL process, double-click SyncHelloWorld.bpel in the Navigator, if it is not already open. Whenever you create a new BPEL project, the visual overview automatically opens.

On the left side of the overview is the client interface, which displays operations exposed by the process and any asynchronous callback operations (there are none for this process). Eclipse BPEL Designer automatically puts any partner link named client on the left side of the window. All other partner links are displayed in a list on the right.

Figure 3-3 Overview of the SyncHelloWorld Process

Description of Figure 3-3  follows
Description of "Figure 3-3 Overview of the SyncHelloWorld Process"

3.5.2 Viewing a Detailed Process Map

The detailed process map provides a visual representation of the flow logic used for the process, from start to end. To display and edit the process map, click Process Map in the visual overview window. Alternatively, you can click the Edit Process Map link. An Inspector pane appears on the right after you drill down into the Process Map view.

At the top of the window, the Overview and Process Map links allow you to shift from the current view (which is the Process Map view) to the Overview view, and back.

Figure 3-4 Detailed Process Map of the SyncHelloWorld Process

Description of Figure 3-4  follows
Description of "Figure 3-4 Detailed Process Map of the SyncHelloWorld Process"

3.5.3 Viewing BPEL Source Code

At the bottom of the window, you can use the BPEL Designer and BPEL Source tabs to switch between graphical editing mode (BPEL Designer) and text-editing mode for the source code of the BPEL process (BPEL Source). Two-way editing is enabled; that is, changes you make in one mode are reflected in the other mode.

Click the BPEL Source tab of the editor window to display the syntax.

Figure 3-5 Source Code of SyncHelloWorld Process

Description of Figure 3-5  follows
Description of "Figure 3-5 Source Code of SyncHelloWorld Process"

3.6 Reviewing the BPEL Source Code

You can use BPEL Source mode to view and edit the BPEL code generated by Eclipse BPEL Designer. This helps you to understand what the designer does, because everything you do in the designer is saved in standard BPEL source code. This also helps you to learn how BPEL generates code if you are not already familiar with it.

The source code has the following main components:

Process Element: Defining the Name and Target Space

The process element, which appears first, defines the name and target namespace you specified.

<process name="SyncHelloWorld"
     targetNamespace="http://tutorial.oracle.com"
     suppressJoinFailure="yes" xmlns:tns="http://tutorial.oracle.com"
     xmlns="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
     xmlns:bpelx="http://schemas.oracle.com/bpel/extension">

Partner Links: Defining Services This Service Uses

After the process element are the partner links, which define the other services or processes with which the process interacts. In this case, the only partner link created automatically by the wizard is the one for the client interface to this BPEL process.

<partnerLinks>
     <partnerLink name="client"
     <!-- comments... -->
          partnerLinkType="tns:SyncHelloWorld"
</partnerLinks>
          myRole="SyncHelloWorldProvider"/>

Global Variables: Variables Accessible Throughout the Process

After the partner links is where you define any global variables that are accessible throughout the process. The New Project wizard automatically creates global variables for the input and output messages for the process. As you saw previously, the types for these two variables are defined in the WSDL for the process.

<variables>     <!-- Reference to the message passed as input during initiation -->
     <variable name="input"
          messageType="tns:SyncHelloWorldRequestMessage"/>
     <!-- Reference to the message that will be returned to the
          requester
          -->
     <variable name="output"
          messageType="tns:SyncHelloWorldResponseMessage"/>
</variables>

Main Body of the Process: Defining the BPEL Activity

After the global variables is the main body of the process, which is any single BPEL activity. This is typically a compound activity that contains subactivities. When you create a new synchronous process, the New Project wizard creates a sequence (which in BPEL is a set of activities executed sequentially) that contains a receive activity to obtain the input message from the client to start the process. This is followed by a reply activity to return the result synchronously to the client.

<sequence name="main">
     <!-- Receive input from requester.
          Note: This maps to operation defined in SyncHelloWorld.wsdl
          -->
     <receive name="receiveInput" partnerLink="client"
          portType="tns:SyncHelloWorld"
          operation="process" variable="input"
          createInstance="yes"/>
     <reply name="replyOutput"
          partnerLink="client"
          portType="tns:SyncHelloWorld"
          operation="process"
          variable="output"/>
</sequence>

Finally, the process is closed:

</process>

In the next section, you can begin to edit this BPEL process to add logic to convert the input into a greeting.

3.6.1 Using the Sequence Activity to Performs Actions Sequentially

A sequence activity contains one or more activities that perform sequentially in the order in which they are listed within the sequence element; that is, in lexical order. The sequence activity completes when the final activity in the sequence has completed. The sequence activity uses the following syntax:

 <sequence standard-attributes>
    standard-elements
    activity+
  </sequence>

For example, the structure for a sequence activity that has a flow activity, scope activity, and pick activity is as follows:

<sequence>
  <flow>
    ...
  </flow>
  <scope>
    ...
  </scope>
  <pick>
    ...
  </pick>
</sequence>

3.6.2 Using the Assign Activity to Assign Values to Variables

The assign activity assigns values to variables. You need to add copy rules to the assign activity to specify which data is being copied into which variable. The source code for an assign activity with copy rules is as follows:

<assign>
     <copy>
        <from expression="concat('Hello ',bpws:getVariableData('input',
          'payload','/tns:name'))"/>
        <to variable="output" part="payload" query="/result"/>
     </copy>
</assign>

If you are using JDeveloper BPEL Designer, this sample is available in Oracle_Home\integration\orabpel\samples\tutorials\101.HelloWorld.


See Also:

  • "Assign Activity"

  • C:\orabpel\samples\references\Assign (for Eclipse BPEL Designer)

  • Oracle_Home\integration\orabpel\samples\references\Assign (for JDeveloper BPEL Designer)


3.7 Adding an Assign Activity to the Process Map

In this section, you learn how to add a new activity to the BPEL process. You follow these steps:

  1. Step 1: Viewing the Process Map

  2. Step 2: Inserting an Assign Activity

  3. Step 3: Adding a Copy Rule

  4. Step 4: Defining the From Part (Source) of the Copy Rule

  5. Step 5: Defining the To Part (Destination) of the Copy Rule

3.7.1 Step 1: Viewing the Process Map

Return to BPEL Designer mode and click the Process Map button to ensure that you are in Process Map view. You now see a graphical representation of the flow for the BPEL process. As described previously, the initial process created by the New Project wizard for a synchronous process just receives the input for the process operation from the client and returns the response with a synchronous reply.

3.7.2 Step 2: Inserting an Assign Activity

Now insert an assign activity into the process. A BPEL assign activity provides a mechanism for doing simple data manipulation using XPath expressions.

You use the assign activity to concatenate the string "Hello " with the string name input message and copy the resulting string into the output message.

To insert a new activity into the process, find it in the BPEL Palette (you can click the More Activities link to see additional activities supported in BPEL Designer mode) and drag it to the location in the flow in which you want to insert it.

  1. From the BPEL Palette, drag an assign activity and drop it between the process receive activity and the reply response activity:

    Description of hello10.gif follows
    Description of the illustration hello10.gif

    The new assign activity is initially selected. You can edit attributes for it in the BPEL Inspector window on the right.

  2. Click in the assign activity's name field (below its icon) and enter a value for the optional name attribute, such as createReturnStr.

  3. Press Enter.

    Description of hello11.gif follows
    Description of the illustration hello11.gif

3.7.3 Step 3: Adding a Copy Rule

Next, you are ready to add a copy rule. In the tasks list (the down arrow to the right of the assign activity heading), click Add Copy Rule.

Description of hello12.gif follows
Description of the illustration hello12.gif

This displays the Copy Rule window, which you use to perform data manipulation. In BPEL, an assign activity can have many copy rules, each using variable data, XPath queries, XPath expressions, and literals to do simple data manipulation and transformation.

Each Copy Rule window for an assign activity has a From part, which specifies the source data, and a To part, which specifies a variable or element part as the destination for the data.

Figure 3-6 Adding a Copy Rule

Description of Figure 3-6  follows
Description of "Figure 3-6 Adding a Copy Rule"


Note:

If you want to perform more complex data transformations using XQuery, XSLT, Java, commercial toolkits, or Web services, see the following Web site for more information:

http://www.oracle.com/technology/bpel


3.7.4 Step 4: Defining the From Part (Source) of the Copy Rule

After you have added the copy rule, you are ready to define its From (source) part.

Follow these steps:

  1. Click Expression in the From part. Enter the following expression in the text field:

    concat( 'Hello ', bpws:getVariableData( 'input', 'payload',
     '/SyncHelloWorldRequest/input'))
    
    

    Alternatively, use the XPath function wizard to complete this with the following steps:

  2. Click the ... context-sensitive BPEL assistant button to start the BPEL Function Wizard.

  3. Select the contact function and click Next.

  4. Enter "Hello " for the firstString (include quotes and add a trailing space after the o).

  5. For the nextString, click the drop-down arrow to use the XPath picker and choose the Variable input, the Part payload, and the XPath Query input.

  6. Click Finish.

    A concat expression similar to the previous one appears, except that the wizard includes the name prefix tns: for the XPath expression.

Whether you enter it directly or use the wizard, this expression says to concatenate the literal string Hello with the string element that is accessed by the XPath query /SyncHelloWorldRequest/input within the part payload of the variable input.


See Also:

The following documentation for more information on XPath expressions and queries:

3.7.5 Step 5: Defining the To Part (Destination) of the Copy Rule

Next, you complete the To section of the Copy Rule window to copy the concatenated string into the helloString element in the reply message.

Follow these steps:

  1. In the To section, click the down arrow after the field.

  2. Select output, then payload, then SyncHelloWorldResponse, and then result string:

    Description of hello20.gif follows
    Description of the illustration hello20.gif

    Eclipse BPEL Designer generates the XPath query string $output/payload/tns:SyncHelloWorldResponse/tns:result and enters it in the field.

    Again, you can always enter queries directly into the field if you choose. The wizard uses fully qualified names (including the namespaces) in the query string, but in both of these examples the namespaces are actually optional.

  3. Click Done.

Next, you are ready to compile and deploy the BPEL process, and then test it.

3.8 Compiling and Deploying the BPEL Process

To compile and deploy the BPEL process:

  1. Save the process.

  2. Click the Build BPEL Project button on the Workbench toolbar to compile and deploy the process.

    Description of hello14.gif follows
    Description of the illustration hello14.gif

This compiles the flow and packages its components into a BPEL suitcase JAR file. You then can deploy this JAR file to Oracle BPEL Server by copying it into the appropriate deployment directory. The build.xml file also deploys the suitcase to the local server's default domain, in this case C:\orabpel\domains\default\deploy. (Note that this action is the same as running obant from the command line.)


Note:

To see the contents of the BPEL suitcase JAR file, open the file C:\orabpel\domains\default\deploy\bpel_SyncHelloWorld_1.0.jar with any tool for opening JAR files (for example, WinZip).

3.9 Testing the BPEL Process

After you have compiled and deployed the BPEL process, you can test it by using the automatically generated test interface in Oracle BPEL Console.

To test the SyncHelloWorld BPEL process:

  1. Access the console at http://localhost:9700/BPELConsole or by selecting Start, then All Programs, then Oracle - Oracle_Home, then Oracle BPEL Process Manager version_number, and then BPEL Console.

    Alternatively, you can click the Open BPEL Console button on the Workbench toolbar to open a browser window that points to the console.

    Description of hello15.gif follows
    Description of the illustration hello15.gif

  2. Log in to the default domain to access the Dashboard tab:

    Description of hello16.gif follows
    Description of the illustration hello16.gif

  3. Click the SyncHelloWorld BPEL process link.

  4. Complete the HTML test form interface.

    Description of hello17.gif follows
    Description of the illustration hello17.gif

  5. Enter your name (this example uses Jane Doe) in the input field and click Post XML Message to initiate the process:

    Description of hello18.gif follows
    Description of the illustration hello18.gif

    You now see the results, because it is a synchronous operation.

  6. To see the visual audit trail for this completed instance, click the Visual Flow link.

    The visual audit trail displays a representation of the current state and history of execution of the instance (which in this case, has completed), with the same look and feel as Eclipse BPEL Designer. You can select activities in the audit trail to view their details. You can also click the Audit tab to see the text audit trail or the Debug tab to see the debugger for this instance.

    Description of hello19.gif follows
    Description of the illustration hello19.gif

  7. Click the reply client activity at the bottom of the audit trail to see the returned XML message for the process, as shown previously.

3.10 Summary

This chapter discusses some of the basic concepts of a BPEL process, and shows the steps necessary to create a BPEL process for a simple Hello World application. These steps are shown in Eclipse BPEL Designer, but you can also use JDeveloper BPEL Designer. This process runs from Oracle BPEL Console. It is a synchronous Web service that can be used as a building block for other BPEL processes or invoked using standard Web services interfaces.