Developer Guide to the BPEL Designer

Using Correlation

Correlation mechanism is used to route messages to the right processes. The section describes how to define correlation.

Understanding Correlation. Using the Correlation Wizard

The BPEL Service Engine runtime uses a mechanism called correlation to track the multiple, long-running exchanges of messages that typically take place between a BPEL process and its partner services. The correlation mechanism helps to route messages to appropriate process instances.

A message in a conversation is connected with a composite value made up of one or more properties defined in a WSDL file. A property is a field within a message identified by a query. Queries are specified by special constructs called property aliases.

Thus, 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.

The following terms apply to correlation:

property is an abitrarily named token. It must be a simple type. It is defined in a WSDL file.
property alias is a rule that tells the BPEL runtime how to map data from a message into a property value. You can define several property aliases for a property that will be used as a correlation value. You would do this if the same property value needs to be mapped from more than one message, which is typical in correlation. For instance, if two different messages have the same part that you want to extract. Then you need one property and two property aliases - one for each message). Property aliases are defined in a WSDL file.
correlation set is defined in a BPEL file. A correlation set is a compound key made up of one or more property values, actually it is a property set. The BPEL runtime uses this key to ensure that messages are routed to the right process instance for a particular conversation.
correlations mark the activities, they identify the correlation sets by name and indicate which correlation sets occur in the messages being sent or received.

Elements That Use and Express Correlation

Correlation sets can be defined for the Process element. The defined correlation sets are then used by message activities (Invoke, Reply, and Receive), which describe a conversation between a process and a partner service.

Correlation sets on Invoke activities are used to verify that outbound messages contain data that is consistent with the data found within specified correlation set instances.

Correlation set names are also used in the onMessage branches of Pick elements and in the onEvent variant of event handlers.

Defining Correlation. The Correlation Wizard

There are two ways to define correlation:

Use the Correlation wizard which will automatically perform all the main steps. This is the most easy and convenient way to define correlation. Usually you do not have to know in details how does correlation work. The Wizard will make it for you.
Define correlation manually

The Correlation Wizard is used to define correlations for two messaging activities, such as Invoke, Reply, Receive, OnEvent or onMessage branch of Pick element.

Note –

The wizard only enables you to create correlation. You can't edit correlation in the wizard.

To create correlation using the Correlation Wizard:

In the Design view, right click the activity that requires correlation and choose Define Correlation. The Correlation Wizard opens.

Step 1. Select the messaging activity. From the drop-down list choose an initiating messaging activity. The activity chosen here will initiate the correlation set. Click Next.

Step 2. Define the correlation. On the left you see a tree structure of the message that initiating activity sends or receives. On the right you see the structure of the message passed by the correlating activity. Connect the messages parts that should be used to define correlation by selecting the node in the source tree pane and dragging the pointer to the node in the destination tree pane.

The correlation is set. The Wizard will create properties and property aliases in a WSDL file, define a correlation set in BPEL, and associate the correlation set with the activities you chose.

Note that properties and property aliases are written to a new WSDL file that you can see among the process files of the BPEL Module. The original WSDL file for the partner service is imported to the new WSDL. For all correlation created using the Wizard, both properties and property aliases are written to this file. Partner WSDL files are imported. The correlation set defined in the BPEL file refers to the new WSDL.

To Define Correlation Manually

Define one or more properties in the WSDL file using the WSDL Editor or To add a property to a WSDL file:.

Define property aliases in the WSDL file using the WSDL Editor orTo add a property to a WSDL file:.

Define a correlation set for the Process in the BPEL file, using one or more of the previously defined properties.

To define a correlation set:
1. In the Design view, right-click the Process element and choose Add > Correlation Set.
  
  Alternatively, in the BPEL Logical View of the Navigator window, right-click the Correlation Sets node and choose Add Correlation Set.
2. In the Add Correlation Set dialog box, specify the name for the correlation set and click Add to add properties.
3. In the Property Chooser dialog box, expand the WSDL file node, and select a property to add to the set.
4. (Optional) Clear the Show Imported Files Only checkbox to view the contents of non-imported WSDL and XML schema files.
  
  By default, the Property Chooser dialog box only shows those files that have already been referenced in the process. However, the project may contain other .wsdl and .xsd files which have not yet been imported into the process. If you select a type for the new property that is defined in a non-imported file, the IDE will automatically add the required import to the BPEL process.
  
  The correlation sets defined for the Process have global visibility. The name of a correlation set must be unique among the names of other correlation sets.
5. Click OK.

Associate one or more correlation sets with a message that is sent or received in an Invoke, Receive, Reply, or Pick activity.
1. In the Design view, double-click an element (Invoke, Receive, Reply, the On Message branch of Pick, or the On Event branch of an Event Handlers container element).
2. In the Property Editor, select the Correlations tab and click Add.
3. In the Choose a Correlation Set dialog box, expand the Correlation Sets node, select the correlation set and click OK.
4. Choose the initiate attribute for this correlation set from the Initiate drop-down list. You can select one of the following options:
  - Yes. The activity must attempt to initiate the correlation set.
  - Join. The activity must attempt to initiate the correlation set if the correlation set is not yet initiated.
  - No. The activity must not attempt to initiate the correlation set. This is the default option.
5. For an Invoke activity, specify the message pattern.
  
  From the Pattern drop-down list, select a pattern attribute to indicate whether the correlation applies to the outbound message (request), inbound message (response), or both (request-response).
6. (Optional) Add more correlation sets as needed and click OK.