Developer Guide to BPEL Designer
The following sections describe, in order of their appearance:
The Invoke element enables the business process to invoke a one-way or request-response operation on a portType offered by a partner. It enables the business process to send messages to partners. The operation is defined in the partner's WSDL.
To use the Invoke element:
As with other elements' property editors, you can change the variables of the Invoke element via a New Variable dialog or via the Variable Chooser. If there is no variable used for an element (for example, no output variable) the New Variable dialog and the Variable Chooser for that variable are not present.
Also, note that when you activate the Browse button in the web service activity property editor, the Input Variable Chooser and the Output Variable Chooser dialog will restrict the list of available variables to those which are of the proper type for the web service operation being configured. In this way the Design view helps you to develop valid BPEL.
Correlation sets on invoke activities, which deal with outbound operations, are used to validate that outgoing messages contain data which is consistent with the data contained within specified correlation set instances.
A tab on the Invoke element property editor enables you to examine or specify a correlation set.
The tab shows:
You can add a correlation set by clicking the Add button.
Correlation is the means by which the BPEL runtime tracks conversations between a particular process instance and corresponding instances of its partner services. You can think of correlation as a primary key that is used by the BPEL runtime to correlate incoming and outgoing messages and route them accordingly.
A correlation set is a collection of properties used by the BPEL runtime to identify the correct process to receive a message. Each property in the correlation set may be mapped to an element in one or more message types through property aliases.
To define a correlation set, messages from partner services must have properties and property aliases defined in the partner WSDL file. You can add properties and property aliases to a WSDL file using the WSDL editor or the Navigator.
After properties and property aliases are added to the WSDL file associated with the project, you can define correlation sets for the Process element.
To define a correlation set:
After defining the correlation set as outlined above, add the correlation set to Invoke, Receive, or Reply elements. You can also associate a correlation set with the onMessage branch of a Pick activity and with an onEvent element within an Event Handlers container.
The following shows a correlation set as seen in the Navigator.
To add a correlation set to an element:
The Receive element allows the business process to do a blocking wait for a particular message to arrive.
A Correlations tab on the Receive element property editor enables you to examine or specify a correlation set.
The tab shows:
You can add a correlation set by clicking the Add button. For more information, refer to Defining a Correlation Set and Adding a Correlation Set to an Element.
Use this activity to return a message from the process to the same partner that initiated the operation
This activity is used in a synchronous (request/response) operation, and specifies the same partner, port type and operation as the Receive activity that invoked the process.
A Correlations tab on the Reply element property editor enables you to examine or specify a correlation set.
The tab shows:
You can add a correlation set by clicking the Add button. For more information, refer to Defining a Correlation Set and Adding a Correlation Set to an Element.
Partner links identify the parties that interact with your business process. Each link is defined by a partner link type and a role name.
The type determines the relationship between a process and its partners by defining the roles played by each service in a conversation. The relationship is further determined by specifying the port type provided by each service to receive messages. Each role specifies one port type in the WSDL file.
Roles determine the conversational aspect of this process or its partner. You use a single role for a synchronous operation as the results are returned using the same operation. You use two roles in an asynchronous operation as the partner role switches during a callback.
It is easy to confuse partner links and partner link types, however:
Partner link types are pre-requisites to the PartnerLink element definition. A PartnerLink element can only be defined by referring to a particular partner link type and role which, as mentioned, must be defined in WSDL.
To add the PartnerLink element to the BPEL project, do one of the following:
Note: When you drag the web service node, the BPEL Designer retrieves the WSDL file from the Application Server. To successfully retrieve the WSDL file, the Application Server has to be running and the web service project has to be deployed.
When you drag the PartnerLink element, a WSDL file node, or a web service node to the diagram, the PartnerLink property editor appears.
The PartnerLink property editor enables you establish partner links for your BPEL processes.
The PartnerLink property editor is invoked by double-clicking a PartnerLink element on the diagram, or right-clicking the PartnerLink element and choosing Edit. The PartnerLink property editor also appears when you drag the PartnerLink element, a WSDL file node, or a web service node to the diagram.
With the PartnerLink property editor, you can specify:
Further on you can choose whether to use the existing partner link type or create a new partner link type.
If the WSDL file you selected contains partner link types, the Use Existing Partner Link Type option is selected and the Partner Link Type drop-down list is populated with the partner link types found in the WSDL file. You can use one of the existing partner link types or select the Use a Newly Created Partner Link Type option to create a new partner link type.
If the WSDL file does not contain partner link types, the Use a Newly Created Partner Link Type option is selected.
You can also review and modify the PartnerLink's properties in the Properties window invoked by right-clicking the element and choosing Properties.
The Empty element has no operation associated with it. It is usually used as a placeholder within a process, to catch and suppress faults, or to help synchronize actions within a flow activity that are executed concurrently.
The Empty element can be used when someone else will be implementing a business process, or when the activities within a flow activity need to be synchronized.
Drag the Empty element from the Palette to the correct path of the diagram.
Use a Wait element to specify a wait condition based on a unit of time or a duration.
Drag the Wait element to the appropriate place in the diagram. Like other elements, it must be placed in the correct position in the process flow; otherwise you will not see the element in the diagram.
Right-click the element in the diagram and choose Properties to invoke a Properties window. Using the Properties window, you can specify:
Use this activity to signal an internal fault.
In defining the properties of this element, you can specify a fault name and a fault variable. These details can then be passed onto a fault handler that is configured to deal with this kind of exception.
The properties of the Throw element can be configured via the Properties window invoked by right-clicking the element and choosing Properties. The options are:
The Assign activity assigns values to variables. You use the Assign element to copy data from one variable to another, construct and calculate the values of expressions, and store new data in variables. Expressions are required to perform simple computation or operate message selections, properties, and literal constants to produce a new value for variables. The Assign activity can contain one or more elementary assignments.
Use the BPEL Mapper to define the copy rules for the Assign activity or add expressions. For more information, refer to the Assign Activity Scenario section of the guide.
The Properties window of the Assign element, invoked by right-clicking the element and choosing Properties, contains two properties:
Use the Flow element to define a set of activities that will execute concurrently (in parallel).
The Flow activity is a structured activity, containing other activities separated into individual control paths or branches . You can embed as many paths in the activity as you want, and they will all be executed simultaneously.
During execution, each path is executed concurrently, and the activities on each are executed in the order in which they appear, unless they are the source of a link. When the activities are the source of a link, the condition of the link and the join condition of the activity must be evaluated. If the link conditions that lead to an activity conflict with those of its join condition, then a fault is thrown on that activity.
Drag the Flow Element from the Palette to the diagram.
Drag an element onto the placeholder inside the Flow element. If you add another element into the same branch of the Flow element, the elements within a branch are automatically wrapped in the Sequence element.
You can add one or more branches to the Flow element. The Flow element has a special user interaction style. It always shows a placeholder for the next branch that you might wish to add. To add a new branch, drag an element from the Palette onto the immediately available "next branch" placeholder.
Use the Sequence element to nest a series of activities into your process. The activities within a sequence will execute in strict sequential order. Process execution returns to the business process when the last activity within the nest has completed.
Drag and drop the Sequence element to the diagram.
You can add one or more child activities to the Sequence. The Sequence element has a special user interaction style. It always shows one or more valid placeholders for the next activity that you might wish to add. To add a new child activity, drag and drop an element from the Palette onto the immediately available next or previous activity placeholder.
The If activity supports conditional behavior of a business process instance. The If activity consists of conditional branches defined by the If and ElseIf elements, followed by an optional Else branch. The conditions on If and ElseIf branches are evaluated in the order they appear. During execution, the first branch whose condition holds true is taken and provides the activity specified for the If activity. In other words, if there are several ElseIf branches whose conditions hold true, only the first of them will be executed.
If none of the branches evaluates to true, then the Else path is chosen. If the Else branch is not explicitly specified, this branch is considered to contain an Empty activity. The If activity is complete when the activity of the selected branch completes.
Drag the activity you want to be executed on the Else branch onto the connector path marked with a slash mark. Configure the nested activity.
In the Design view, drag the ElseIf branch that you want reordered and drop it onto the placeholder that appears next to another ElseIf branch.
The Pick element blocks the process and waits until one of the specified events occurs. After the specific event occurs, the activity associated with this event is performed. The possible events are the arrival of a message or a timer-based alarm. The occurrence of the events is mutually exclusive. If more than one of the events occurs, then the selection of the activity to perform depends on which event occurred first.
The Pick activity provides two branches, onMessage and onAlarm. The branch whose condition is satisfied first (i.e. a message is received or the specified timer expires) is executed. When you add a Pick element to your diagram, it automatically includes one onMessage statement in which you specify the properties of the message that the process awaits from a partner service. Each Pick element must include at least one onMessage statement. The onAlarm branch contains a timer you can use to specify how long the process is to wait.
The Properties window for the Pick element, invoked by right-clicking the element and choosing Properties, includes the following fields:
The Scope activity is essentially a collection of child activities that can have their own Message Exchange, Variables, Fault and Event Handlers. A Scope activity provides the behavior context for the child elements. The attributes defined for a parent Scope have local visibility inside this Scope. For example, the variables declared for a Scope are visible only inside that Scope and all nested Scopes. These variables can then be used for the child activities of this Scope.
Variables are used in BPEL programming as in other software languages: they hold temporary values, form part of expressions, or are passed as a parameter to external partners. Normally, you need a variable for every message sent to or received from a partner service. The BPEL Designer supports the following types of variables:
Global and Local Variables
The variables defined at the Process root are global variables, which have a global visibility throughout the entire process. The variables defined within a particular Scope are visible only inside that Scope and all nested Scopes. These variables are called local variables. A variable defined for an inner Scope element can hide an upper defined variable of the same name.
The name of a variable must be unique among the names of all variables defined within the same Scope.
To define a variable:
By default, the Create New Variable dialog only shows those files that have already been imported into the process. However, the project may contain other .wsdl and .xsd files that have not yet been imported into the process. If you define a new variable based on a type defined in one of the non-imported files, the IDE will automatically add the required import to the BPEL process.
You can also add variables from the Navigator window. To add a variable, select BPEL Logical View in the Navigator, expand your BPEL Module project's node, right-click the Variables node and choose Add Variable.
To edit a variable:
Note: In this release, the BPEL Mapper does not support working with variables defined for the Scope element.
Use the While element to repeatedly execute one or more activities as long as specific conditions are in place at the beginning of each iteration. This element contains other elements that are repeated while success criteria you specify are met. If the condition you specify leads to false, none of the activities listed will be executed.
Note: the While element first checks the validity of the condition and then executes the iterative activity. Conversely, the Repeat Until element first executes the activity and then checks the validity of the condition.
The Process element is already present in your diagram. The New Project wizards always create a skeletal BPEL file that contains at least a process element. Therefore, the Process element is not part of the Palette. The Process element is assumed to be present, as it is the minimum requirement for a BPEL file.
The following screenshot shows the representation of a process in the Travel Reservation Service sample.
A BPEL process can be synchronous or asynchronous. A synchronous BPEL process blocks the client (the one which is using the process) until the process finishes and returns a result to the client. An asynchronous process does not block the client. Rather it uses a callback to return the result (if any). Usually we use asynchronous processes for longer-lasting processes and synchronous for processes that return a result in a relatively short time. If a BPEL process uses asynchronous web services, the process itself is usually also asynchronous.
Use the Repeat Until element to repeatedly execute one or more activities as long as specific conditions are in place after the execution of each iteration. This element contains other elements that are repeated until the success criteria you specify are met. If the condition you specify leads to true, the activities listed will be executed once.
Note: the Repeat Until element first executes the iterative activity and then checks the validity of the condition. Conversely, the While element first checks the validity of the condition and then executes the activity.
Use the For Each element to repeatedly execute its contained scope activity exactly N+1 times where N equals the Final Counter Value minus the Start Counter Value.
The Properties window for the For Each element includes the properties listed below.
Use this activity to halt the execution of an activity or a process: either within the process, within a structured activity, or within a handler.
Drag the Exit element from the Palette to the diagram.
Note: The BPEL runtime does not support Exit within the Flow and OnAlarm elements, or within the OnEvent child of the EventHandler element.