16 Coordinating Master and Detail Processes

This chapter describes how to coordinate master and detail processes in a BPEL process. This coordination enables you to specify the tasks performed by a master BPEL process and its related detail BPEL processes. This is sometimes referred to as a parent and child relationship.

This chapter includes the following sections:

Section 16.1, "Introduction to Master and Detail Process Coordinations"
Section 16.2, "Defining Master and Detail Process Coordination in Oracle JDeveloper"

16.1 Introduction to Master and Detail Process Coordinations

Master and detail coordinations consist of a one-to-many relationship between a single master process and multiple detail processes.

For example, assume a business process imports sales orders into an application. Each sales order consists of a header (customer information, ship-to address, and so on) and multiple lines (item name, item number, item quantity, price, and so on).

The following tasks are performed to execute the order:

Validate the header. If the header is invalid, processing stops.
Validate each line. If any lines are invalid, they are marked as invalid and processing stops.
Perform inventory checks for each item. If an item is not available, a work order is created to assemble it.
Stage items at the shipping dock after items for each line are available.
Ship the order to the customer.

To perform these tasks, create a master process to check and validate each header and multiple BPEL processes to check and validate each line item.

Potential coordination points are as follows:

The master process must signal the detail processes that header validation is successful and to continue processing.
Each detail process must signal the master process after line item validation is complete.
Each detail process must signal the master process after the line item is available in inventory.
After all line items are available, the master must signal each detail process to move its line item to the shipping dock (the dock may become too crowded if items are simply moved as soon as they are available).
After all lines have been moved, the master process must execute logic to ship the fulfilled order to the customer.

Figure 16-1 provides an overview of the header and line item validation coordination points between one master process and two detail processes.

Figure 16-1 Master and Detail Coordination Overview (One BPEL Process to Two Detail Processes)

Description of "Figure 16-1 Master and Detail Coordination Overview (One BPEL Process to Two Detail Processes)"

The following BPEL process activities coordinate actions between the master and detail processes:

signal: notifies the other processes (master or detail) to continue processing
receive signal: waits until it receives the proper notification signal from the other process (master or detail) before continuing its processing

Both activities are coordinated with label attributes defined in the BPEL process files. Labels are declared per master process definition.

Figure 16-2 provides an overview of the BPEL process flow coordination.

Figure 16-2 Master and Detail Syntax Overview (One BPEL Process to One Detail Process)

Description of "Figure 16-2 Master and Detail Syntax Overview (One BPEL Process to One Detail Process)"

As shown in Figure 16-2, each master and detail process includes a signal and receive signal activity. Table 16-1 describes activity responsibilities based on the type of process in which they are defined.

Table 16-1 Master and Detail Process Coordination Responsibilities

If A...	Contains A...	Then...
Master process	Signal activity	The master process signals all of its associated detail processes at runtime.
Detail process	Receive signal activity	The detail process waits until it receives the signal executed by its master process.
Detail process	Signal activity	The detail process signals its associated master process at runtime that processing is complete.
Master process	Receive signal activity	The master process waits until it receives the signal executed by all of its detail processes.

If the signal activity executes before the receive signal activity, the state set by the signal activity is persisted and still effective for a later receive signal activity to read.

16.1.1 BPEL File Definition for the Master Process

The BPEL file for the master process defines coordination with the detail processes. The BPEL file shows that the master process interacts with the partner links of several detail processes. Example 16-1 provides an example.

Example 16-1 BPEL File Definition for the Master Process

<process name="MasterProcess"
. . .
. . .
  <partnerLinks>
    <partnerLink name="client"
             partnerLinkType="tns:MasterProcess"
             myRole="MasterProcessProvider"
             partnerRole="MasterProcessRequester"/>
    <partnerLink name="DetailProcess"
             partnerLinkType="dp:DetailProcess"
             myRole="DetailProcessRequester"
             partnerRole="DetailProcessProvider"/>
    <partnerLink name="DetailProcess1"
             partnerLinkType="dp1:DetailProcess1"
             myRole="DetailProcess1Requester"
             partnerRole="DetailProcess1Provider"/>
    <partnerLink name="DetailProcess2"
             partnerLinkType="dp2:DetailProcess2"
             myRole="DetailProcess2Requester"
             partnerRole="DetailProcess2Provider"/>
  </partnerLinks>

A signal activity shows the label value and the detail process coordinated with this master process. The label value (startDetailProcess) matches with the label value in the receive signal activity of all detail processes. This ensures that the signal is delivered to the correct process. There is one signal process per receive signal process. The master process signals all detail processes at runtime. This syntax shows a signal activity in a BPEL process that supports BPEL version 1.1.

<bpelx:signal name="notifyDetailProcess" label="startDetailProcess" to="details"/>

Note:

In BPEL 2.0, the signal activity syntax is slightly different. The signal activity is wrapped in an extensionActivity element.

<extensionActivity>
   <bpelx:signal name="notifyDetailProcess" 
                 label="startDetailProcess" to="details"/>
</extensionActivity>

Assign, invoke, and receive activities describe the interaction between the master and detail processes. This example shows interaction between the master process and one of the detail processes (DetailProcess). Similar interaction is defined in this BPEL file for all detail processes.

In the invoke activity, ensure that the Invoke As Detail checkbox is selected. Figure 16-3 provides details.

Figure 16-3 Invoke As Detail Checkbox

Description of "Figure 16-3 Invoke As Detail Checkbox"

This selection creates the partner process instance (DetailProcess) as a detail instance. You must select this checkbox in the invoke activity of the master process for each detail process with which to interact. Example 16-2 provides an example of the BPEL file contents after you select the Invoke As Detail checkbox.

Example 16-2 bpelx:invokeAsDetail Attribute

<assign>
   <copy>
     <from variable="input" part="payload" query="/tns:processInfo/tns:value"/>
     <to variable="detail_input" part="payload" query="/dp:input/dp:number"/>
   </copy>
</assign

<invoke name="receiveInput" partnerLink="DetailProcess"
        portType="dp:DetailProcess"
        operation="initiate" 
        inputVariable="detail_input" 
        bpelx:invokeAsDetail="true"/>

<!--  receive the result of the remote process -->
<receive name="receive_DetailProcess" partnerLink="DetailProcess"
            portType="dp:DetailProcessCallback"
            operation="onResult" variable="detail_output"/>

The master BPEL process includes a receive signal activity. This activity indicates that the master process waits until it receives a signal from all of its detail processes. The label value (detailProcessComplete) matches with the label value in the signal activity of each detail process. This ensures that the signal is delivered to the correct process. Example 16-3 provides an example. This syntax shows a receive signal activity in a BPEL process that supports BPEL version 1.1.

Example 16-3 Receive Signal Activity

<bpelx:receiveSignal name="waitForNotifyFromDetailProcess" 
                     label="detailProcessComplete" 
                     from="details"/>

Note:

In BPEL 2.0, the receive signal activity syntax is slightly different. The receive signal activity is wrapped in an extensionActivity element.

<extensionActivity>
   <bpelx:receiveSignal name="waitForNotifyFromDetailProcess" 
   label="detailProcessComplete" from="details"/>
</extensionActivity>

16.1.1.1 Correlating a Master Process with Multiple Detail Processes

For environments in which you have one master and multiple detail processes, use the bpelx:detailLabel attribute for signal correlation. Example 16-4 shows how to use this attribute.

The first invoke activity invokes the DetailsProcess detail process and associates it with a label of detailProcessComplete0.

Example 16-4 First Invoke Activity

<invoke name="invokeDetailProcess" partnerLink="DetailProcess"
        portType="dp:DetailProcess"
        operation="initiate" 
        inputVariable="detail_input" 
        bpelx:detailLabel="detailProcessComplete0"
        bpelx:invokeAsDetail="true"/>

The second invoke activity invokes the DetailsProcess1 detail process and associates it with a label of detailProcessComplete1. Example 16-5 provides an example.

Example 16-5 Second Invoke Activity

<invoke name="invokeDetailProcess1" partnerLink="DetailProcess1"
        portType="dp1:DetailProcess1"
        operation="initiate" 
        inputVariable="detail_input1" 
        bpelx:detailLabel="detailProcessComplete1-2"
        bpelx:invokeAsDetail="true"/>

The third invoke activity invokes the DetailsProcess2 detail process again through a different port and with a different input variable. It associates the DetailsProcess2 detail process with a label of detailProcessComplete1-2, as shown in Example 16-6.

Example 16-6 Third Invoke Activity

<invoke name="invokeDetailProcess2" partnerLink="DetailProcess2"
        portType="dp2:DetailProcess2"
        operation="initiate" 
        inputVariable="detail_input2" 
        bpelx:detailLabel="detailProcessComplete1-2"
        bpelx:invokeAsDetail="true"/>

The receive signal activity of the master process shown in Example 16-7 waits for a return signal from detail process DetailProcess0.

Example 16-7 Receive Signal Activity

<!-- This is a receiveSignal waiting for 1 child to signal back -->
<bpelx:receiveSignal name="waitForNotifyFromDetailProcess0"
label="detailProcessComplete0" from="details"/>

The second receive signal activity of the master process shown in Example 16-8 also waits for a return signal from DetailProcess1 and DetailProcess2.

Example 16-8 Second Receive Signal Activity

<!-- This is a receiveSignal waiting for 2 child (detail) processes to signal back -->
<bpelx:receiveSignal name="waitForNotifyFromDetailProcess1-2"
   label="detailProcessComplete1-2" from="details"/>

Note:

If there is only one receive signal activity in the BPEL process, do not specify the bpelx:detailLabel attribute in the invoke activity. In these situations, a default bpelx:detailLabel attribute is assumed and does not need to be specified.

16.1.2 BPEL File Definition for Detail Processes

The BPEL process file of each detail process defines coordination with the master process.

A receive signal activity indicates that the detail process shown in Example 16-9 waits until it receives a signal executed by its master process. The label value (startDetailProcess) matches with the label value in the signal activity of the master process.

Example 16-9 startDetailProcess Label Value

<bpelx:receiveSignal name="waitForNotifyFromMasterProcess"
   label="startDetailProcess" from="master"/>

A signal activity indicates that the detail process shown in Example 16-10 signals its associated master process at runtime that processing is complete. The label value (detailProcessComplete) matches with the label value in the receive signal activity of each master process.

Example 16-10 Signal Activity

<bpelx:signal name="notifyMAsterProcess" label="detailProcessComplete"
   to="master"/>

16.2 Defining Master and Detail Process Coordination in Oracle JDeveloper

This section provides an overview of how to define master and detail process coordination in Oracle BPEL Designer. In this example, one master process and one detail process are defined.

Note:

This section only describes the tasks specific to master and detail process coordination. It does not describe the standard activities that you define in a BPEL process, such as creating variables, creating assign activities, and so on.

16.2.1 How to Create a Master Process

To create a master process:

In the SOA Composite Editor, create a BPEL process service component. For this example, the process is named MasterProcess.
Double-click the MasterProcess BPEL process.
In the Component Palette, expand Oracle Extensions.
Drag a Signal activity into the designer.
Double-click the Signal activity.

This activity signals the detail process to perform processing at runtime.

Enter the details described in Table 16-2:

Table 16-2 Signal Dialog Fields and Values

Field	Value
Name	Enter a name (for this example, `contactDetailProcess`).
Label	Enter a label name (for this example, `beginDetailProcess`). This label must match the receive signal activity label you set in the detail process in Step 6.
To	Select details as the type of process to receive this signal.

Figure 16-4 shows the Signal dialog.

Figure 16-4 Signal Dialog

Description of "Figure 16-4 Signal Dialog"

Click OK.
Drag a Receive Signal activity into the designer.
Double-click the Receive Signal activity.

This activity enables the master process to wait until it receives the signal executed by all of its detail processes.

Enter the details shown in Table 16-3:

Table 16-3 Receive Signal Dialog Fields and Values

Field	Value
Name	Enter a name (for this example, `waitForDetailProcess`).
Label	Enter a label name (for this example, `completeDetailProcess`). This label must match the signal activity label you set in the detail process in Step 10.
To	Select details as the type of process from which to receive the signal.

Figure 16-5 shows the Receive Signal dialog.

Figure 16-5 Receive Signal Dialog

Description of "Figure 16-5 Receive Signal Dialog"

Click OK.

The master process has now been designed to:
- Signal the detail process to perform processing at runtime.
- Wait until it receives the signal executed by the detail process.

16.2.2 How to Create a Detail Process

To create a detail process:

In the SOA Composite Editor, create a second BPEL process service component. For this example, the process is named DetailProcess.
Double-click the DetailProcess BPEL process.
In the Component Palette, expand Oracle Extensions.
Drag a Receive Signal activity into your BPEL process service component.
Double-click the Receive Signal activity.

This activity enables the detail process to wait until it receives the signal executed by its master process.

Enter the details shown in Table 16-4:

Table 16-4 Receive Signal Dialog Fields and Values

Field	Value
Name	Enter a name (for this example, `WaitForContactFromMasterProcess`).
Label	Enter a label name (for this example, `beginDetailProcess`). This label must match the signal activity label you set in the master process in Step 6.
To	Select master as the type of process from which to receive the signal.

Figure 16-6 shows the Receive Signal dialog.

Figure 16-6 Receive Signal Dialog

Description of "Figure 16-6 Receive Signal Dialog"

Click OK.
Drag a Signal activity into the designer.
Double-click the Signal activity.

This activity enables the detail process to signal its associated master process at runtime that processing is complete.

Enter the details described in Table 16-5:

Table 16-5 Signal Dialog Fields and Values

Field	Value
Name	Enter a name (for this example, `contactMasterProcess`).
Label	Enter a label name (for this example, `completeDetailProcess`). This label must match the receive signal activity label you set in the master process in Step 10.
To	Select master as the destination.

Figure 16-7 shows the Signal dialog.

Figure 16-7 Signal Dialog

Description of "Figure 16-7 Signal Dialog"

Click OK.

The detail process has now been designed to:

Wait until it receives the signal executed by its master process.
Signal the master process at runtime that processing is complete.

16.2.3 How to Create an Invoke Activity

To create an invoke activity:

Return to the MasterProcess master process.
In the Component Palette, expand BPEL Constructs.
Drag an Invoke activity into your BPEL process service component.
Double-click the Invoke activity.
Select the DetailProcess BPEL process you created in Step 1 as the partner link.
Complete all remaining fields in the Invoke dialog, and click OK.
In the designer, click Source.
Select the Invoke As Detail checkbox in the invoke activity. The BPEL file appears as shown in Example 16-11.
Example 16-11 bpelx:invokeAsdetail Attribute
```
<invoke name="MyInvoke" partnerLink="DetailProcess"
   portType="dp:DetailProcess" 
   operation="initiate"
   inputVariable="detail_input"
   bpelx:invokeAsDetail name="true"/>
```
This attribute creates the partner process (DetailProcess) as a detail instance.
If this is an environment in which one master process is interacting with multiple detail processes, perform the following tasks:
1. Specify the bpelx:detailLabel attribute for correlating with the receive signal activity, as shown in Example 16-12.
  Example 16-12 bpelx:detailLabel Attribute
```
<invoke name="MyInvoke" partnerLink="DetailProcess"
   portType="dp:DetailProcess" 
   operation="initiate"
   inputVariable="detail_input"/>
   bpelx:detailLabel="detailProcessComplete0"
   <bpelx:invokeAsdetail name="true"/>
```
2. Specify the same label value of detailProcessComplete0 in the receive signal activity of the master process, as shown in Example 16-13.
  Example 16-13 detailProcessComplete0 Label Value
```
<bpelx:receiveSignal name="waitForNotifyFromDetailProcess0-1"
label="detailProcessComplete0" from="details"/>
```
3. Repeat these steps as necessary for additional detail processes, ensuring that you specify a different label value.
From the File main menu, select Save All.

Master and detail coordination design is now complete.