Creating a Correlation Set
A correlation set is a collection of properties (simple types like an int or a string) that uniquely identify a particular instance of a running process.
For each property in the set you must define a property alias. The property alias describes where to find the property values and is defined in a WSDL file. A correlation property may be passed into the process as one of the inputs, or it may be obtained from the outputs of a service that is invoked.
Using correlation you can create stateful processes that you can call multiple times to perform an operation on a “persistent” data set. In this very simple example, a process is called twice, two values are added together, and then the sum of the values is returned.
A process that contains more than one Receive or a Pick activity must have a correlation set. For information on Pick activities, see Pick.
Before you can take advantage of correlation you must enable the correlation property tab. To do this: from the Windows menu, select Preferences > BPEL Properties, clear the Simple Mode option, and check Correlation.
An Example: Using Correlation
In this example, the process will run more than once, adding two or more values (of type int) together and returning the sum of the values. The value of the instanceID string will be used to uniquely identify which instance of the process you want to run. This is similar to a context or state ID.
There are a few basic steps to create and run this example.
- Create the process
- Configure the correlation set
- Define the process
- Associate the correlation set with the appropriate activities
- Watch it work
This example assumes that you are familiar with creating a simple process, including using the WSDL editor, activity palette, and copy rule dialog box.
Step 1: Create the process
Open the project and in the WSDL Editor make sure the process takes a single int value as input and then returns the sum. In this example the value of the instance ID string uniquely identifies which instance of the process you want to run.
The process output is an int value:
Step 2: Configure the correlation set
From the Outline view, right-click Correlation Sets and choose Add Correlation Set to add an empty set.
In the Add Correlation Set dialog box, choose a name for the correlation set. In this example we used the name CorrelationSet. You cannot use names that contain spaces or other special characters and each correlation set name must be unique within the process. Click OK.
On the Add Correlation Property dialog box, choose the property name and type. The property defines the correlation set. In this example we used the name instanceID of type string.
Click Next to add a correlation property alias. To associate the correlation set property with the process input value you created, you define a property alias. Each property in the correlation set must have a property alias defined. The property alias describes where to find the property values.
After you have created the correlation property and associated it with the property alias, the correlation properties display on the Properties tab. To view the property alias associated with the property, hover over the property and press F2. Double-click the alias to display the Edit Property Alias dialog box.
Step 3: Define the process
Using the palette and BPEL Editor, finish building your process, creating copy rules for the Assign activities. The final AssignSumOfValues uses an XPath expression to return the sum.
If you use the same activity names as this example, your final process should look like this:
This process calls the service twice. First you supply an int value which the process returns. The instance stops on the ReceiveSecondValue activity, waiting for a call with the second value. When the second call occurs the process takes the second value and returns the sum of the first and second values.
Step 4: Associating the correlation set with the activities
How is the correlation set configured so you can locate the same process instance and call it a second time?
- Click the Correlation tab on the property view of the ReceiveFirstValue activity.
- Click Add to add the Receive activity.
From the Initiation drop down list, choose Yes. The correlation set is associated with the first Receive activity. This means that the process will receive the first value from the user, and reply with the same value; but the second time the process is called, the second value is received and the reply will be the sum of the two values.
For the second ReceiveSecondValue activity settings, follow the same steps, except set the Initialization column to No. This means that the second time the process is run, rather than initialize the correlation set, the set should be used to locate a particular instance of the process; in this case, the same instance that was called the first time.
Seeing it Work
To test the process, pass in the value as well as the instanceID field that you defined. This is the string you used to identify the process instance. To access the same instance the second time, make sure to pass in the second value using the same instanceID.
Since in this particular process there are only two Receive activities, the process only waits to be run twice. After the sum is returned on the second run, the process completes and the instance is terminated. If you were to call it again with the same instanceID, the process would start over at the beginning; a new instance would be spawned for that instanceID and the value you supplied would be treated as the first value.