4 Getting Started with Oracle BPEL Process Manager

This chapter describes how to get started with Oracle BPEL Process Manager. BPEL process creation is described, along with key BPEL design features such as activities, partner links, adapters, and monitors.

This chapter includes the following sections:

4.1 Introduction to the BPEL Process Service Component

This section provides an introduction to the BPEL process service component in the design environment.

4.1.1 How to Add a BPEL Process Service Component

You add BPEL process service components in the SOA Composite Editor.

To add a BPEL process service component:

  1. Follow the instructions in Table 4-1 to start Oracle JDeveloper.

    Table 4-1 Starting Oracle JDeveloper

    To Start... On Windows... On UNIX...

    Oracle JDeveloper

    Click JDev_Oracle_Home\jdeveloper\JDev\bin\jdev.exe or create a shortcut

    $ORACLE_HOME/jdev/bin/jdev


  2. Add a BPEL process service component through one of the following methods:

    As a service component in an existing SOA composite application:

    1. From the Component Palette, drag a BPEL Process service component into the SOA Composite Editor.

    In a new application:

    1. From the Application Navigator, select File > New > Applications > SOA Application.

      This starts the Create SOA Application wizard.

    2. In the Application Name dialog, enter an application name in the Application Name field.

    3. In the Directory field, enter a directory path in which to create the SOA composite application and project.

    4. Click Next.

    5. In the Project Name dialog, enter a name in the Project Name field.

    6. Click Next.

    7. In the Project SOA Settings dialog, select Composite With BPEL Process.

    8. Click Finish.

    Each method causes the Create BPEL Process dialog shown in Figure 4-1 to appear.

    Figure 4-1 Create BPEL Process Dialog

    Create BPEL process
    Description of "Figure 4-1 Create BPEL Process Dialog"

  3. Provide the required details, as described in Table 4-2.

    Note:

    You cannot use BPEL 1.1 and BPEL 2.0 syntax in the same .bpel file. However, you can include BPEL 1.1 and BPEL 2.0 projects in the same SOA composite application.

    Table 4-2 Create BPEL Process Dialog

    Field Description

    BPEL Specification

    Select the type of BPEL process to create.

    • BPEL 1.1 Specification

      Creates a BPEL project that supports the BPEL 1.1 specification. This is the default selection.

    • BPEL 2.0 Specification

      Creates a BPEL project that supports the BPEL 2.0 specification.

    Name

    Enter a name for the BPEL process or accept the default name. The name you enter becomes the file name for the BPEL process, Web Services Description Language (WSDL), and componentType files in the Application Navigator.

    Always use completely unique names when creating BPEL processes. Do not create the following:

    • A process name that begins with a number (for example, 1SayHello)

    • A process name that includes a dash (for example, Say-Hello)

    • Two processes with the same name, but with different capitalization (for example, SayHello and sayhello).

      This is particularly important for business intelligence (BI) data object names, which are generated on the Oracle BAM server in all upper case format. For example, if you create a BPEL process named BPELProcess1, a BI name of BI_DEFAULT_PROJECT1_BPELPROCESS1 is generated for the Oracle BAM BI data object after deployment. If you create two BPEL processes, BPELProcess1 and BPELPRocess1, the same BI data object name is generated.

    • A process name that exceeds 500 characters.

    • A non-ASCII process name. The BPEL process name is used in directory and file names of the SOA project, which can cause problems.

    Namespace

    Use the default namespace path or enter a custom path.

    Template

    Select a template based on the type of BPEL process service component you want to design. A template provides a basic set of default files in the Application Navigator (process_name.wsdl, process_name.bpel, and process_name.componentType) with which to begin designing your BPEL process service component.

    • Asynchronous BPEL Process: Creates an asynchronous process with a default receive activity to initiate the BPEL process service component flow and an invoke activity to asynchronously call back the client. This type is selected by default. For more information, see Chapter 8, "Invoking an Asynchronous Web Service from a BPEL Process."

    • Synchronous BPEL Process: Creates a synchronous process with a default receive activity to initiate the BPEL process service component flow and a reply activity to return the results. For more information, see Chapter 7, "Invoking a Synchronous Web Service from a BPEL Process."

    • One Way BPEL Process: Creates a process with a one-way call interface definition.

    • Define Service Later: Select to create an empty BPEL process service component with no activities.

    • Base on a WSDL: Creates a BPEL process with an interface defined by an existing WSDL file. You must specify the WSDL Uniform Resource Locator (URL), port type, and callback port type to use.

    • Subscribe to Events: Creates a BPEL process in which you can subscribe to a business event. After selecting this option, the dialog refreshes to display an event table. Click the Add icon to select an event to which to subscribe. Your selection is then displayed in the event table. You can then select the consistency level and whether to publish this event. You can also click the Filter icon to create a filter expression for the selected event. This selection launches the Expression Builder dialog. For more information, see Chapter 41, "Using Business Events and the Event Delivery Network."

    Service Name

    Accept the default value or enter the name of the service this process is exposing. When you open an invoke, receive, OnMessage, or reply activity, the service name appears by default in the Partner Link field. This name is the same name as the partner link.

    Expose as a SOAP Service

    Select this checkbox to create a BPEL process service component that is automatically connected (wired) to an inbound simple object access protocol (SOAP) web service binding component. If you do not select this checkbox, the BPEL process service component is created as a standalone component in the SOA Composite Editor. You can explicitly associate the BPEL process service component with a service at a later time. This checkbox is selected by default.

    Delivery

    Set the persistence policy of the process in the delivery layer. This list enables you to specify a value for the oneWayDeliveryPolicy deployment descriptor property. This field is displayed if you select an asynchronous or one-way BPEL process in the Template list. The possible values are:

    • async.persist: Messages are persisted in the database. With this setting, reliability is obtained with some performance impact on the database. In some cases, overall system performance can be impacted. This is the default value.

    • async.cache: Incoming delivery messages are kept only in the in-memory cache. If performance is preferred over reliability, consider this setting. When set to async.cache, if the rate at which one-way messages arrive is much higher than the rate at which they are delivered, or if the server fails, messages can be lost. In addition, the system can become overloaded (messages become backlogged in the scheduled queue) and you can receive out-of-memory errors. Consult your own use case scenarios to determine if this setting is appropriate.

      When you set oneWayDeliveryPolicy to async.cache in high availability environments, invoke and callback messages in the middle of execution at the time of a server crash may be lost or duplicated. Server failover is not supported for async.cache. For more information, see Oracle Fusion Middleware High Availability Guide.

    • sync: Direct invocation occurs on the same thread. The scheduling of messages in the invoke queue is bypassed, and the BPEL instance is invoked synchronously. In some cases this setting can improve database performance.

    For information about transaction and fault propagation semantics for this property, see Chapter 13, "Transaction and Fault Propagation Semantics in BPEL Processes."

    For information about changing the value of this property in the Property Inspector, see Section C.1.1, "How to Define Deployment Descriptor Properties in the Property Inspector."

    Transaction

    Set the transaction behavior of the BPEL instance for initiating calls. This list enables you to specify a value for the transaction deployment descriptor property. This field is displayed if you select a synchronous BPEL process in the Template list. The possible values are:

    • requiresNew: A new transaction is created for the execution, and the existing transaction (if there is one) is suspended. This behavior is true for both request/response (initiating) environments and one-way, initiating environments in which the Delivery list value (oneWayDeliveryPolicy property) is set to sync.

    • required: In request/response (initiating) environments, this setting joins a caller's transaction (if there is one) or creates a new transaction (if there is no transaction). In one-way, initiating environments in which the Delivery list value (oneWayDeliveryPolicy property) is set to sync, the invoke message is processed using the same thread in the same transaction. This is the default value.

    Note: This property does not apply for midprocess receive activities. In those cases, another thread in another transaction is used to process the message. This is because a correlation is needed and it is always done asynchronously.

    For information about transaction and fault propagation semantics for this property, see Chapter 13, "Transaction and Fault Propagation Semantics in BPEL Processes."

    For information about changing the value of this property in the Property Inspector, see Section C.1.1, "How to Define Deployment Descriptor Properties in the Property Inspector."

    Input

    Accept the default input XSD schema or click the Search icon to select a different XSD. If you click the Search icon, the Type Chooser dialog appears. Browse the imported schemas and select the input element (for example, a purchase order). You can also import an existing schema or WSDL in the Type Chooser dialog

    Output

    Accept the default output XSD schema or click the Search icon to select a different XSD. If you click the Search icon, the Type Chooser dialog appears. Browse the imported schemas and select the output element (for example, a purchase order).


  4. Click OK.

    Oracle BPEL Designer displays the sections shown in Figure 4-2.

    Figure 4-2 Oracle BPEL Designer Sections

    Description of Figure 4-2 follows
    Description of "Figure 4-2 Oracle BPEL Designer Sections"

    Each section of this view enables you to perform specific design and deployment tasks. Table 4-3 identifies the sections listed in Figure 4-2.

    Table 4-3 Oracle JDeveloper Sections

    Element Description

    Application Navigator

    Displays the process files of a SOA project. Key files include the following:

    • composite_name (composite.xml)

      Describes the entire SOA composite application. For more information about this file, see Section 2.1.2, "What Happens When You Create a SOA Application and Project."

    • .bpel

      Depending upon the process type you selected, initially contains a minimal set of activities. (If you selected to create an asynchronous process, then receive and invoke activities appear.) You add syntax to this file when you drag activities, create variables, create partner links, and so on.

    • .componentType

      Describes the services and references for the BPEL process service component.

    • .wsdl

      The WSDL client interface, which defines the input and output messages for this BPEL process flow, the supported client interface and operations, and other features. This functionality enables the BPEL process flow to be called as a service.

    • monitor.config

      Defines runtime and deployment properties needed to connect with Oracle BAM Server to create the Oracle BAM data objects and dashboards.

    Designer

    Provides a visual view of the BPEL process service component that you design. This view displays when you perform one of the following actions:

    • Double-click the .bpel file name in the Application Navigator.

    • Click the Design tab at the bottom of the designer with the .bpel file selected.

    • Double-click the BPEL process component in the SOA Composite Editor.

    As you design the BPEL process service component by dragging activities, creating partner links, and so on, the Design window changes.

    Component Palette

    Displays the available activities to add to the BPEL process service component. Activities are the building blocks. The BPEL Constructs and Oracle Extensions selections of the Component Palette display a set of activities that you drag into the designer of the BPEL process service component. The Component Palette displays only those pages relevant to the state of the designer. BPEL Constructs or Oracle Extensions are nearly always visible. However, if you are designing a transformation in a transform activity, the Component Palette only displays selections relevant to that activity, such as String Functions, Mathematical Functions, and Node-set Functions.

    Structure window

    Provides a structural view of the data in the BPEL process service component currently selected in the designer. You can perform a variety of tasks from this section, including:

    • Importing schemas.

    • Defining message types.

    • Managing (creating, editing, and deleting) elements such as variables, aliases, correlation sets, and partner links.

    • Editing activities in the BPEL process flow sequence that displays in the designer.

    Log window

    Displays messages about the status of validation and compilation. To ensure that a BPEL process service component validates correctly, you must ensure that the following information is correct:

    • The BPEL process service component must have an input variable.

    • A partner link must be selected.

    • A partner role must be selected.

    • The operation must not be empty.

    • The input variable type must match the partner link operation type.

    If deployment is unsuccessful, messages appear that describe the type and location of the error.

    Source window

    View the syntax inside the BPEL process service component files. As you drag activities and partner links, and perform other tasks, the syntax in these source files is immediately updated to reflect these changes.

    History window

    Displays the revision history of a file and read-only and editable versions of a file side-by-side.

    Property Inspector

    Displays details about an activity. Single-click an activity in the Design window to display details.


    Note:

    To learn more about these sections, you can also place the cursor in the appropriate section and press F1 to display online Help.

  5. Click the icon above the Oracle BPEL Designer to view the BPEL project version (either 1.1 or 2.0). Figure 4-3 provides details.

    Figure 4-3 BPEL Project Version

    Description of Figure 4-3 follows
    Description of "Figure 4-3 BPEL Project Version"

4.2 Introduction to Activities

Activities are the building blocks of a BPEL process service component. Oracle BPEL Designer includes a set of activities that you drag into a BPEL process service component. You then double-click an activity to define its attributes (property values). Activities enable you to perform specific tasks within a BPEL process service component. For example, here are several key activities:

Figure 4-7 shows an example of a property window (for this example, an invoke activity). In this example, you invoke a partner link named StoreFrontService and define its attributes.

Figure 4-7 Invoke Activity Example

Description of Figure 4-7 follows
Description of "Figure 4-7 Invoke Activity Example"

The invoke activity enables you to specify an operation you want to invoke for the service (identified by its partner link). The operation can be one-way or request-response on a port provided by the service. You can also automatically create variables in an invoke activity. An invoke activity invokes a synchronous service or initiates an asynchronous web service.

The invoke activity opens a port in the process to send and receive data. It uses this port to submit required data and receive a response. For synchronous callbacks, only one port is needed for both the send and the receive functions.

For more information about activities, see Appendix A, "BPEL Process Activities and Services."

For information about copying and pasting activities in the same project or between projects, see Section A.2.2, "Copying and Pasting Activities in BPEL Projects."

4.3 Introduction to Partner Links

A partner link enables you to define the external services with which the BPEL process service component is to interact. You can define partner links as services or references (for example, through a JCA adapter) in the SOA Composite Editor or within a BPEL process service component in Oracle BPEL Designer. Figure 4-8 shows the partner link icon (in this example, named PartnerSupplierMediator).

Figure 4-8 PartnerLink Icon

Description of Figure 4-8 follows
Description of "Figure 4-8 PartnerLink Icon"

A partner link type characterizes the conversational relationship between two services by defining the roles played by each service in the conversation and specifying the port type provided by each service to receive messages within the conversation.

Figure 4-9 shows an example of the attributes of a partner link for a service.

Figure 4-9 Partner Link Dialog

Description of Figure 4-9 follows
Description of "Figure 4-9 Partner Link Dialog"

Table 4-4 describes the fields of this dialog.

Table 4-4 Create Partner Link Dialog Fields

Field Description

Name

A unique and recognizable name you provide for the partner link.

Process

Displays the BPEL process service component name.

WSDL URL

The name and location of the WSDL file or Java interface that you select for the partner link. Click the SOA Service Explorer icon (second icon from the left above the WSDL URL field) to access a window for selecting the WSDL file or Java interface to use.

Java interfaces display for selection under the References folder with a name of javaEJB. If the component with which you are wiring this partner link uses WSDL files and you select a Java interface and click OK, a message displays indicating that this component requires a WSDL interface. If you click Yes, a compatible WSDL file is created based on the Java interface.

For more information about integrating components that use Java interfaces into SOA composite applications, see Chapter 52, "Integrating the Spring Framework in SOA Composite Applications."

Partner Link Type

The partner link defined in the WSDL file.

Partner Role

The role performed by the partner link.

My Role

The role performed by the BPEL process service component. If this is a synchronous process case, the BPEL process service component does not have a role.


Note:

The Partner Link Type, Partner Role, and My Role fields in the Create Partner Link dialog are defined and required by the BPEL standard.

Best Practice:

As a best practice, always create and wire Oracle Mediator and BPEL process service components in the SOA Composite Editor, instead of in Oracle BPEL Designer.

If you add an Oracle Mediator or BPEL process partner link to your BPEL process in Oracle BPEL Designer and connect either partner link to your BPEL process through an invoke activity, the wiring is not automatically reflected above in the SOA Composite Editor. You must explicitly wire the Oracle Mediator or BPEL process service component to your BPEL process again in the SOA Composite Editor.

This is not an issue with human task or business rule partner links in Oracle BPEL Designer; both are also automatically wired in the SOA Composite Editor.

4.4 Creating a Partner Link

The method by which you create partner links within the BPEL process in Oracle BPEL Designer impacts how the partner link displays in the SOA Composite Editor. This section describes this impact. The WSDL file can be on the local operating system or hosted remotely (in which case you need a URL for the WSDL).

Likewise, creating and wiring a service or reference binding component to a BPEL process service component in the SOA Composite Editor causes a partner link to display in Oracle BPEL Designer.

4.4.1 How to Create a Partner Link

To create a partner link:

  1. In the SOA Composite Editor, double-click the BPEL process service component.

    Oracle BPEL Designer is displayed.

  2. In the Component Palette, expand BPEL Constructs.

  3. Drag a Partner Link into the appropriate Partner Links swimlane, as shown in Figure 4-10.

    Figure 4-10 Partner Link Creation in Oracle BPEL Designer

    Description of Figure 4-10 follows
    Description of "Figure 4-10 Partner Link Creation in Oracle BPEL Designer"

    The Create Partner Link dialog appears.

  4. Complete the fields for this dialog, as described in Table 4-4.

The following sections describe the impact of partner link creation on the SOA Composite Editor.

4.4.1.1 Partner Links for an Outbound Adapter

Table 4-5 describes the impact on the SOA Composite Editor.

Table 4-5 Impact of Partner Link Creation on the SOA Composite Editor

Creating the Following for a BPEL Process in Oracle BPEL Designer... Displays the Following in the SOA Composite Editor...

A partner link for an outbound adapter

  • A reference handle for the BPEL process service component

  • A reference representing the outbound adapter in the composite

  • A wire connecting the BPEL process service component to the adapter reference


Figure 4-11 shows how this method of creation appears in the SOA Composite Editor.

Figure 4-11 SOA Composite Editor Impact

Description of Figure 4-11 follows
Description of "Figure 4-11 SOA Composite Editor Impact"

4.4.1.2 Partner Links for an Inbound Adapter

Table 4-6 describes the impact on the SOA Composite Editor.

Table 4-6 Impact of Partner Link Creation on the SOA Composite Editor

Creating the Following for a BPEL Process in Oracle BPEL Designer... Displays the Following in the SOA Composite Editor...

A partner link for an inbound adapter

  • A service for the BPEL process service component

  • A service representing the inbound adapter in the composite

  • A wire connecting the inbound adapter service to the BPEL process service component


Figure 4-12 shows how this method of creation appears in the SOA Composite Editor.

Figure 4-12 SOA Composite Editor Impact

Description of Figure 4-12 follows
Description of "Figure 4-12 SOA Composite Editor Impact"

4.4.1.3 Partner Links from an Abstract WSDL to Call a Service

Table 4-7 describes the impact on the SOA Composite Editor.

Table 4-7 Impact of Partner Link Creation on the SOA Composite Editor

Creating the Following for a BPEL Process in Oracle BPEL Designer... Displays the Following in the SOA Composite Editor...

A partner link from an abstract WSDL to call a service

A reference handle with an interface and callback interface defined for the BPEL process service component


4.4.1.4 Partner Links from an Abstract WSDL to Implement a Service

Table 4-8 describes the impact on the SOA Composite Editor.

Table 4-8 Impact of Partner Link Creation on the SOA Composite Editor

Creating the Following for a BPEL Process in Oracle BPEL Designer... Displays the Following in the SOA Composite Editor...

A partner link is created from an abstract WSDL to implement a service

A service with an interface and callback interface for the BPEL process service component is created.

Note: If an external SOAP reference with the specified interface and callback interface exists in the SOA Composite Editor, you can either create a new external SOAP reference and wire to it or wire to the existing external SOAP reference.


Figure 4-13 shows how this method of creation appears in the SOA Composite Editor.

Figure 4-13 SOA Composite Editor Impact

Description of Figure 4-13 follows
Description of "Figure 4-13 SOA Composite Editor Impact"

4.4.1.5 Partner Links and Human Tasks or Business Rules

Table 4-9 describes the impact on the SOA Composite Editor.

Table 4-9 Impact of Partner Link Creation on the SOA Composite Editor

Creating the Following for a BPEL Process in Oracle BPEL Designer... Displays the Following in the SOA Composite Editor...

A human task or business rule is created

  • A human task or business rule in the composite

  • A reference for the BPEL process service component

  • A wire connecting the BPEL process service component to the new human task or business rule


Figure 4-14 shows how this method of creation appears in the SOA Composite Editor.

Figure 4-14 SOA Composite Editor Impact

Description of Figure 4-14 follows
Description of "Figure 4-14 SOA Composite Editor Impact"

4.4.1.6 Partner Links from an Existing Human Task, Business Rule, or Oracle Mediator

Table 4-10 describes the impact on the SOA Composite Editor.

Table 4-10 Impact of Partner Link Creation on the SOA Composite Editor

Creating the Following for a BPEL Process in Oracle BPEL Designer... Displays the Following in the SOA Composite Editor...

A partner link by dragging an existing human task, business rule, or mediator service component into the BPEL process

  • A reference for the BPEL process service component

  • A wire connecting the BPEL process service component to the existing human task, business rule, or mediator


Figure 4-15 shows how this method of creation appears in the SOA Composite Editor.

Figure 4-15 SOA Composite Editor Impact

Description of Figure 4-15 follows
Description of "Figure 4-15 SOA Composite Editor Impact"

4.5 Introduction to Adapters

The Partner Link dialog shown in Figure 4-9 also enables you to take advantage of another key feature that Oracle BPEL Process Manager and Oracle JDeveloper provide. Click the Service Wizard icon shown in Figure 4-16 to access the Adapter Configuration wizard.

Figure 4-16 Defining an Adapter

Description of Figure 4-16 follows
Description of "Figure 4-16 Defining an Adapter"

Adapters enable you to integrate the BPEL process service component (and, therefore, the SOA composite application as a whole) with access to file systems, FTP servers, database tables, database queues, sockets, Java Message Services (JMS), Oracle User Messaging Service, and MQ. You can also integrate with services such as HTTP binding, direct binding, EJB, and others. This wizard enables you to configure the types of services and adapters shown in Figure 4-17 for use with the BPEL process service component:

Figure 4-17 Service and Adapter Types

Description of Figure 4-17 follows
Description of "Figure 4-17 Service and Adapter Types"

For information about the service and adapter types, see Chapter 37, "Getting Started with Binding Components."

When you select an adapter type, the Service Name dialog shown in Figure 4-18 prompts you to enter a name. For this example, File Adapter was selected in Figure 4-17. When the wizard completes, a WSDL file by this service name appears in the Application Navigator for the BPEL process service component (for this example, named USPSShipment.wsdl). The service name must be unique within the project. This file includes the adapter configuration settings you specify with this wizard. Other configuration files (such as header files and files specific to the adapter) are also created and display in the Application Navigator.

Figure 4-18 Adapter Service Name

Description of Figure 4-18 follows
Description of "Figure 4-18 Adapter Service Name"

The Adapter Configuration wizard dialogs that appear after the Service Name dialog are based on the adapter type you selected.

You can also add adapters to your SOA composite application as services or references in the SOA Composite Editor.

For more information about technology adapters, see Oracle Fusion Middleware User's Guide for Technology Adapters.

4.6 Introduction to BPEL Process Monitors

You can configure BPEL process monitors in Oracle BPEL Designer by selecting Monitor at the top of Oracle BPEL Designer. Figure 4-19 provides details. BPEL process monitors can send data to Oracle BAM for analysis and graphical display through the Oracle BAM adapter.

Figure 4-19 BPEL Process Monitors

Description of Figure 4-19 follows
Description of "Figure 4-19 BPEL Process Monitors"

For more information, see Section 53.3, "Using Oracle BAM Monitor Express With BPEL Processes."