Using Correlation Sets, Properties, and Property Aliases in BPEL

Every BPEL business process is a web service so it may seem that you only need to know the destination port in order to send a message to a BPEL process. However, since business processes are stateful and are instantiated to act based on their state, BPEL correlation sets are used to support stateful collaboration between web services in a standardized, implementation independent way.

Correlation sets rely on the correlation data tokens stored in the message envelopes, headers, or business documents themselves. The declaration of correlation relies on the declarative properties of messages. A property is simply a field within a message identified by a query. Queries are specified by special constructs called property aliases.

Opening, Deploying, and Testing Sample Projects

This section begins with a simple HelloWorld business process. Initially, this process is a synchronous one and does not require correlation sets. In the beginning the process just receives a user name and returns back the Hello <User Name > message. In this section you will open and test the process.

This tutorial includes a zipped project called HelloWorldSample.

To open the HelloWorldSample and HelloWorldSampleCompApp projects:

1. In your file system, create a directory named HelloTut.
2. Download the bpel-correl-helloworld.zip file and extract it into the HelloTut directory.
3. From the IDE's main menu, choose File > Open Project.
   The Open Project wizard opens.
4. Navigate to the HelloTut > HelloWorldSample directory, select both the HelloWorldSample and HelloWorldSampleCompApp projects, and click Open Project Folder.
   A progress dialog box appears, and then the Open Project dialog box appears.
   Note: A progress dialog box opens, and then the Open Project dialog box opens to notify you of a reference problem.
   At this point in this tutorial, this is normal behavior because the composite application has a dependency on the JBI module.
   
5. To resolve the broken reference, right-click the HelloWorldSampleCompApp project and select Resolve Reference Problems.
6. In the Resolve Reference Problems dialog box, click Resolve.
7. In the Browse Project dialog box, navigate to and select the HelloWorldSample project and click Open Project Folder.
   The Resolve Reference Problems dialog box now shows that the problem is resolved.
8. Click Close to close the Resolve Reference Problems dialog box.

To deploy the HelloWorldSampleCompApp project:

1. Right-click the HelloWorldSampleCompApp and choose Deploy.
   The Select Server dialog box displays.
2. Select the GlassFish V 2 as the target application server and click OK.
3. Wait until the BUILD SUCCESSFUL message appears in the Output window.
   Note: If the Output window is not visible, choose Window > Output from the main menu.
4. To verify that the HelloWorldSampleCompApp application is successfully deployed, switch to the Runtime window.
5. Expand GlassFish V2 > JBI > Service Assemblies.
   If a HelloWorldSampleCompApp node appears under the Service Assemblies node, the application was successfully deployed.

top

To test the HelloWorldSampleCompApp project:

1. In the Projects window, expand HelloWorldSampleCompApp > Test > SendUserName1.
2. Double-click Output to examine its contents.
   Notice that Output.xml is empty. The first test run will populate Output.xml with the real output. Subsequent test runs will compare the real output against the contents of Output.xml.
3. In the Projects window, right-click the SendUserName1 node and choose Run from the pop-up menu.
   In this test you send a user name to the process which returns the preset Hello Michael message back to the client to verify that the process works fine.
   Note: The first run is a special case because Output.xml is empty and the output is written to Output.
   Notice the failed message in the JUnit Test Results window.
   The Overwrite Empty Output dialog box opens so you can confirm that you want to overwrite Output.xml.
4. Click Yes.
   After the first run, Output is no longer empty. The contents of Output.xml are preserved and are not overwritten by the new result.
5. Repeat step 3.

Click to enlarge

top

Adding State to a Sample Business Process

In this section you will add another Receive activity to the HelloWorld business process. This activity adds asynchronous communication to the process and the process becomes a stateful one.
The resulting message returned by the process will be extended with the prefix string.

To add state to a sample business process:

1. In the Projects window, expand HelloWorldSample > Process Files.
2. Double-click the HelloWorldProcess.bpel file.
   The HelloWorldProcess.bpel file opens in the Design view of the BPEL Designer.
3. In the Web Service section of the Design view Palette, select the Receive icon and drag your selection to the placeholder between the ReceiveUserName and AddHello activities.
   The IDE provides visual clues about where to drop the selection. This action adds a Receive activity called Receive1 to the diagram.
   Notice that an error sign displays to the right of the added activity since the activity has no correlation defined yet.
   You are going to resolve this later in Creating and Adding the Correlation Set.
   

   

4. Double-click the Receive1 activity.
   The Receive1[Receive] - Property Editor opens.
5. In the Name field, type SetPrefix.
6. From the Partner Link drop-down list, select ProcessInterface.
7. From the Operation drop-down list, select setPrefix.
8. Create a new input variable by doing the following:
   1. Click the Create button next to the Input Variable field.
      The New Input Variable dialog box opens.
   2. Change the value in the Name field to Prefix.
   3. Click OK.
9. Click OK to close the Receive1 [Receive] - Property Editor.
   The Receive activity is now labeled SetPrefix in the Design view.
10. Double-click the AddHello activity.
    The BPEL Mapper displays at the bottom of the IDE.
11. Add a prefix to the user name in the output greeting string by doing the following in the BPEL Mapper window:
    
    1. Select the existing link between the Variables > UserNameRequest > part1 > data node and the string2 part of the Concat function and press Delete.
    2. In the left tree pane, expand Variables > Prefix > part1.
    3. Select data and drag the pointer to the string2 part of the Concat function.
    4. In the left tree pane, expand UserNameRequest>part1.
    5. Select data and drag the pointer to the string3 part of the Concat function.
    6. Press Ctrl-S to save your edits.
       

       

By completing the steps in this section, you added an asynchronous communication to the process.
Now, after the first message is received and the process is initialised, the BPEL process needs to wait for another message at the SetPrefix activity.
Imagine a situation where several process instances are instantiated and all of them are waiting for a message at the second Receive activity.
The BPEL Service Engine uses correlation sets to decide which process instance the message was sent to.
As a result of the changes above the process returns the greeting string extended with the Mr. prefix in this example.
Notice that you do not set the prefix value anywhere, it is automatically concatenated from the SendPrefix test to the greeting message and the concatenated message comes back if this test passes successfully.

top

Defining Correlation Properties and Property Aliases

In this section you will define correlation properties and property aliases. Properties are typically used to store tokens for correlation of service instances with messages. You use property aliases to specify which part of the data is to be extracted from messages and with which property the extracted data needs to be associated.

To create a property:

1. Choose Window > Navigating > Navigator from the main menu.
2. In the Design view, select the HelloWorldProcess business process.
   The Navigator window shows the BPEL Logical View. The BPEL Logical View shows a structured view of the business process.
3. In the Navigator window, expand Imports.
   Note: You use HelloWorldProcessWSDLWrapper.wsdl to add required properties and property aliases.
   The information to identify the correct process instance is taken from the identification field of the incoming messages.
   Next you need to define a property to store the correlation token.
4. Right-click the /HelloWorldProcessWSDLWrapper.wsdl node and choose Add Property from the pop-up menu.
   The Create New Correlation Property dialog box appears.
   Note: You must specify a property name and type to define a property.
   The property name is used to refer to the property in correlation sets and property aliases and can be any valid name.
   Property type specifies the type of correlation data to be stored in the property.
5. In the Name field, type MyProperty.
6. Choose string as the property type in the Built-in Types tree.
7. Click OK.
   This action closes the Create New Correlation Property dialog box and adds the MyProperty subnode below the HelloWorldProcessWSDLWrapper.wsdl node.
8. Expand the HelloWorldProcessWSDLWrapper.wsdl node to see the property you created.
   

   

Now you need to create a property alias to specify how correlation data is extracted from the messages.
As you have two Receive activities that receive messages of different types, you need to define two property aliases (one for each message type).

To create the first property alias:

1. In the Navigator window, expand Imports.
2. Right-click the HelloWorldProcessWSDLWrapper.wsdl node and choose Add Property Alias from the pop-up menu.
   The Create New Property Alias dialog box appears.
   Note: You need to specify the property, message part and query to create a property alias. The specified property is used to store an extracted correlation token, the message part helps to map the property alias to some specific message and its part, and the query is used to specify which data in particular needs to be extracted.
3. In the Create New Property Alias dialog box, click Browse.
   The Property Chooser dialog box appears.
4. Expand the HelloWorldProcessWSDLWrapper.wsdl node and select MyProperty.
5. Click OK.
6. In the Create New Property Alias dialog box, expand HelloWorldProcessWSDL.wsdl and getHelloRequest.
7. Choose part1 as a message part.
8. Specify /UserData/id in the Query text field.
9. Click OK.
   The created property alias is added as a subnode to the My Property node.
   

   

To create the second property alias:

1. In the Navigator window, expand Imports.
2. Right-click the HelloWorldProcessWSDLWrapper.wsdl node and choose Add Property Alias from the pop-up menu.
   The Create New Property Alias dialog box appears.
3. In the Create New Property Alias dialog box, click Browse.
   The Property Chooser dialog box appears.
4. Expand the HelloWorldProcessWSDLWrapper.wsdl node and select MyProperty.
5. Click OK.
6. In the Create New Property Alias dialog box, expand HelloWorldProcessWSDL.wsdl and setPrefixRequest.
7. Choose part1 as a message part.
8. Specify /Prefix/id in the Query text field.
9. Click OK.
   The created property alias is added as a subnode to the MyProperty node.
   

   

top

Creating and Adding the Correlation Set

A correlation set is a named collection of properties that specifies which data should be extracted from incoming messages. This data is later used to identify the target process instance.
As soon as properties and property aliases are defined you can create a correlation set.

To create a correlation set:

1. In the Design view, select the HelloWorldProcess business process.
2. Right-click the process and choose Add > Correlation Set.
   The Add Correlation Set dialog box appears.
3. In the Name field, type MyCorrelationSet.
4. Click Add.
   The Property Chooser dialog box appears.
5. Expand HelloWorldProcessWSDLWrapper.wsdl and select MyProperty.
6. Click OK to add the property.
7. In the Add Correlation Set dialog box, click OK to create the correlation set.

After the correlation set is created, you need to add it to the activities that receive/send messages.

To add the correlation set to the ReceiveUserName activity:

1. In the Design view, select the ReceiveUserName activity.
2. Right-click the activity and choose Edit from the pop-up menu.
   The ReceiveUserName[Receive]-PropertyEditor dialog box appears.
3. On the Correlations tab, click Add.
   The Choose a Correlation Set dialog box appears.
4. Choose MyCorrelationSet in the tree and click OK.
5. On the Correlations tab of the ReceiveUserName[Receive]-PropertyEditor, set the value of MyCorrelationSet in the Initiate column to yes.
   

   

   
   This means the correlation data is to be initialized with the data received in this activity.
6. Click OK.
   MyCorrelationSet is added as a subnode to the ReceiveUserName node in the Navigator BPEL Logical View.
   

   

Now you need to map the correlation data to the SetPrefix activity. This helps the BPEL engine associate incoming data with process instances.

To add the correlation set to the SetPrefix activity:

1. In the Design view, select the SetPrefix activity.
2. Right-click the activity and choose Edit from the pop-up menu.
   The SetPrefix[Receive]-PropertyEditor dialog box appears.
3. On the Correlations tab, click Add.
   The Choose a Correlation Set dialog box appears.
4. Choose MyCorrelationSet in the tree and click OK.
5. On the Correlations tab of the SetPrefix[Receive]-PropertyEditor, make sure the value of MyCorrelationSet in the Initiate column is set to no.
   

   

6. Click OK.
   MyCorrelationSet is added as a subnode to the SetPrefix node in the Navigator BPEL Logical View.
   Notice that the error sign to the right of the SetPrefix activity on the diagram disappears since the activity got the correlation defined.
   

   

top

Debugging and Testing BPEL Process

In this section you check that the process we designed works fine.
You debug the process and verify that the expected output is returned from the runtime.

1. Open the Projects window.
2. Right-click the HelloWorldSampleCompApp project and choose Clean and Build Project from the pop-up menu.
3. Wait until the BUILD SUCCESSFUL message appears in the Output window.
4. Right-click the HelloWorldSampleCompApp project and choose Debug Project (BPEL) from the pop-up menu to start the debugging session.
5. Wait until the Debug session started message appears in the BPEL Debugger Console window.
6. In the Design view, select the ReceiveUserName activity.
7. Right-click the activity and choose Toggle Breakpoint.
   A red box appears at the top of the activity with a breakpoint.
   

   

8. Right-click the AddHello activity and choose Toggle Breakpoint to set another breakpoint.
9. In the Projects window, expand HelloWorldSampleCompApp > Test.
10. Right-click the SendUserName2 test and choose Run.
    The passed activities on the diagram become marked with green indicators.
    

    
    Click to enlarge

11. As soon as the process stops at the first breakpoint, click Continue on the Debugging toolbar (Ctrl+F5) toolbar to resume the process.
    The process resumes and stops at the SetPrefix activity.
12. In the Projects window, right-click the SendPrefix test and choose Run.
    The process resumes and stops at the second breakpoint that you set at the AddHello activity.
13. Click Continue on the Debugging toolbar (Ctrl+F5) toolbar to resume the process.
    Note: Like in step 3 of the To test the HelloWorldSampleCompApp project part, the JUnit Test Results window displays the failed message and the Overwrite Empty Output confirmation message is displayed.
14. Click Yes.
    On the completion of the process the SendPrefix test passes successfully.
    

    
    Click to enlarge

15. In the Projects window, double-click the node with the output of the SendUserName2 test in the HelloWorldCompApp > Test > SendUserName2 > Ouput node. The output of the SendUserName2 test contains the Hello Mr. Michael expected extended greeting string.
    This means the process worked fine and the BPEL runtime correctly handled the asynchronous communication using the MyCorrelationSet correlation set.
    

    
    Click to enlarge

16. Select Run > Finish Debugger Session from the main menu.

Note: If you disable the MyCorrelationSet correlation set, the process never reaches the AddHello activity since there is no correlation data that can help the BPEL service engine to route messages to the correct process instance.

Summary

In this tutorial, you explored creating correlation sets, properties and property aliases and their role in a stateful business process. You also learned how to add correlation sets to web service activities, develop and test sample processes.

---

top