UI

The UI consists of a read-only field in the Diagram properties tab under the Collaborations subset and a dialog for edition. It works similarly to the imports field, So basically, a read-only text box containing correlation details and a button. The button opens a dialog showing a table. In that table, it is possible to create the correlations, set their properties, and define property types.

For the correlation property binding itself, there is a new subset called Correlation, located in the properties tab and available for the following nodes:

• Start Message
• Intermediate Catch Message
• Boundary event message

BPMN Specification

Collaboration

The first part of this specification is, of course, collaboration. The essential bit here is the id and name attributes. They are auto-generated and not configurable. The id is random-unique and, the name is a constant value. 

<bpmn2:collaboration id="{UniqueID}" name="Default Collaboration"/>

Inside the above node, the first child is the participant. Again we have a random-unique id, a constant name, and the processRef value is the same as the process id.

<bpmn2:participant id="{UniqueID}" name="Pool Participant" processRef={process.id}/>

<bpmn2:process id="ANYNAME" …/>

Next, we have the correlation key. The node attributes can be edited in the Correlations Dialog and correspond to the first and second columns (ID, Name).

<bpmn2:correlationKey id="{ID}" name="{Name}"/>

Last, one level below is the correlationPropertyRef. This node references a supporting node, addressed below. But for practical reasons, we can say it relates to the 3rd column (Property ID) in the Correlations dialog.

<bpmn2:correlationPropertyRef>{Property ID}</bpmn2:correlationPropertyRef/>

Regarding UI and collaboration node spec, it is necessary to highlight the relation between correlation keys and their properties. For every correlationPropertyRef in the .bpmn file, there is a corresponding row in the dialog UI. It might sound complex at first. But can be easily explained by the following images. 

Below, the dialog configuration.

And here, the collaboration node from that dialog.

<bpmn2:collaboration id="_CFF5EBBF-FA48-44FC-B165-82D94E46A43F" name="Default Collaboration">
   <bpmn2:participant id="_99AC338B-ABAD-472B-82D8-A77A78D7D218" name="Pool Participant" processRef="myProcessID" />
   <bpmn2:correlationKey id="CK_ID_1" name="CK Name 1">
       <bpmn2:correlationPropertyRef>CP_ID_1</bpmn2:correlationPropertyRef>
       <bpmn2:correlationPropertyRef>CP_ID_2</bpmn2:correlationPropertyRef>
   </bpmn2:correlationKey>
   <bpmn2:correlationKey id="CK_ID_2" name="CK Name 2">
       <bpmn2:correlationPropertyRef>CP_ID_1</bpmn2:correlationPropertyRef>
       <bpmn2:correlationPropertyRef>CP_ID_Other</bpmn2:correlationPropertyRef>
       <bpmn2:correlationPropertyRef>CP_ID_Another</bpmn2:correlationPropertyRef>
   </bpmn2:correlationKey>
   <bpmn2:correlationKey id="CK_ID_3" name="CK Name 3">
       <bpmn2:correlationPropertyRef>CP_ID_Yet_Another</bpmn2:correlationPropertyRef>
   </bpmn2:correlationKey>
</bpmn2:collaboration>
 
<bpmn2:process id="myProcessID" ... />

Correlation Property

Another crucial part is the correlationProperty node. Set in the same level as the collaboration node. Its attributes id and name are editable and correspond to the 3rd and 4th columns in the dialog (Property ID, Property Name). The type attribute refers to an item definition created based on the value of the 5th column (Property Type). 

bpmn2:correlationProperty id="{Property ID}" name="{Property Name}" type="{itemDefintion.id(Property Type)}"/>

This item definition consists of two attributes. First, is id and uses the Property ID plus the word _TypeDef (e.g., CP_ID_1_TypeDef, CP_ID_Other_TypeDef). The last is structureRef and holds the actual value used in the Property Type column from the Correlations dialog.

<bpmn2:itemDefinition id="{Property ID}TypeDef" structureRef="{Property Type}"/>

As a child of the correlationProperty, we have the correlationPropertyRetrievalExpression. This node uses values provided by the Correlation subset and is responsible for tying together a property and a message. In this particular case, the first field (Correlation Property). The attribute id is random-unique, and messageRef points to the message node id. 

<bpmn2:correlationPropertyRetrievalExpression id="{Unique ID}" messageRef="{message.id}">

In the message node, itemRef relates to an item definition. Similar to correlation property. But this time, it uses the value from the Message Expression Type field, also in the Correlation subset.

<bpmn2:message id="ANYID" itemRef="{itemDefintion.id(Message Expression Type)}" name="{Message}"/>

Last, inside the correlationPropertyRetrievalExpression, we have the messagePath. The relevant attributes are id, with a random-unique value, evalutesToTypeRef, which refers to the same itemDefinition as the message node itemRef, and the node value itself. The latter corresponds to the Message Expression field in the Correlation subset.

<bpmn2:messagePath xsi:type="bpmn2:tFormalExpression" id="{Unique ID}" evaluatesToTypeRef="{itemDefintion.id(Message Expression Type)}" language="{Message Expression Language}">{Message Expression}</bpmn2:messagePath>

To summarize, each row in the Collaboration dialog represents a collaboration property node. This node uses data from the Collaborations dialog and the Correlation subset. It creates item definitions on which it can rely and utilizes data from other supporting nodes.

Subscription

Closing the collaboration spec is the correlationSubscription. The id is random-unique, and the correlationKeyRef points to a correlationKey using the id attribute.

<bpmn2:correlationSubscription id="{Unique ID}" correlationKeyRef="{correlationKey.id}">

As a child of the correlationSubscription comes the correlationsPropertyBinding. Similar to the previous node, here, the id is random-unique. But, the second attribute, correlationPropertyRef, points to a correlationProperty also using the id.

<bpmn2:correlationPropertyBinding id="{Unique ID}" correlationPropertyRef="{correlationProperty.id}">

Last, one level inside correlationsPropertyBinding lies the dataPath. Comparable to messagePath, it has a random-unique id, but the other attributes are related to the Data Expression fields instead of the Message Expression ones.

<bpmn2:dataPath xsi:type="bpmn2:tFormalExpression" id="{Unique ID}" evaluatesToTypeRef="{itemDefintion.id(Data Expression Type)}" language="{Data Expression Language}">{Data Expression}</bpmn2:dataPath>
 

In sum, the subscription is straightforward. It is easy to identify the one-to-one relation between correlationKey and correlationSubscription. Similarly, the same applies to all correlationProperty nodes belonging to that key and the correlationPropertyBinding nodes.

Testing

Automated test for Visual Studio Code plugin will be implemented. Test will cover happy-path scenario for adding correlation with properties and setting its type to the process
and working with correlation properties on message nodes.
Negative scenarios, adding unsupported/invalid data etc., to the table must be handled on component level with unit tests.