Merge of Sequence Diagrams

Introduction

Sequence diagrams are a special case for LemonTree, which comes with its own difficulties. In a sequence diagram, positions are important not only for the look-and-feel of a diagram, but also for its semantics.

This means that merging sequence diagrams correctly is possilby even more important than other diagram types.

However, this stands in conflict with LemonTree's philosophy as a merge tool. LemonTree neither interprets nor merges the semantics of the models it processes.

Example

An example is always good for understanding (especially in this case). Let us consider this simplified sequence diagram for an ATM transaction:

Figure 1: Simplified ATM transaction sequence diagram

The following paragraphs detail multiple variants of parallel changes to this sequence diagram and the potential pitfalls when merging them with LemonTree.

Possible Consequences Of Different Modifications

Adding/Removing/Moving Messages At Different Positions

Adding Messages

Different types of conflicts can occur when messages have been added at different positions to different versions of a sequence diagram.

To demonstrate this, two change-sets have been applied to our ATM example:

• Version A has a new message after insert(card)
• Version B has two new messages after pin ok()

Merging these two versions (with the correct base model) will lead to this merge preview:

Figure 2: Merge Preview of Conflict caused by adding messages in parallel

Which looks fine at first glance. However, the problem is that adding these new message has changed the properties of all of the following messages in both models, leading to conflicts for all of these messages aswell, even though they haven't been edited.

If you look at these conflicts in the property viewer, you will see something like this:

Figure 3: Conflicting Properties of unchanged messages

The affected properties are:

• PtStartX: The starting position of the message on the X-Axis
• PtStartY: The starting position of the message on the Y-Axis
• SeqNo: The position of the message relative to the other messages

Removing Messages

Similar conflicts can occur when removing messages aswell. To demonstrate this, we will edit version B further by removing the message verify pin():

Figure 4: Message verify pin() has been deleted

This will cause similar problems to the above example, as the position information of all messages after the deleted one will also be affected. 

Moving Messages

Similar conflicts can occur when removing messages aswell. To demonstrate this, we will restore the message verify pin() in version B, and move it to a different position instead.

Figure 5: Message verify pin() has been moved

This will cause similar problems to the above example, as the position information of all messages after the moved one will also be affected. 

Recommendation

Due to the complex nature of the problem, there's no one-size-fits-all solution for these types of conflicts.   The general recommendation is to take the properties from the side (A or B) that you think fits is less work to fix up, and the re-adjust the diagram manually in Enterprise Architect afterwards.

Adding A Message At The Same Position Without Moving Other Messages

A special case within this special diagram type occurs when both versions of the model have added a new message at the same position in the model without moving any of the other messages.

Sucha modification can be seen here:

Figure 6: Messages added at the same position in A and B

This case is tricky to detect with LemonTree. All of the following messages will receive new SeqNo values, but, because these values will be increased by 1 in both A and B, they will be identical in both models. As such, LemonTree doesn't detect a conflict in this scenario at all.

Recommendation

Should such a case occur, the consequences in the merge model depend on the PtStartX/PtStartY assigned to the respective new messages. The messages may appear on top of each other, or in an order that is not semantically correct. Currently, this must be manually rectified by the modeller after the merge.

Moving Lifelines

Concurrently moving lifelines will also result in conflicts. The result of such a move can be seen here:

Figure 7: Conflict caused by conflicting moves of lifeline elements

Moving the lifelines has changed their page index (stored as value cx as apart of the PDATA property) to different values in both A and B.

Recommendation

If this is the only change to the PDATA property, you can safely pick the PDATA from either side. You should still check the result in the merge model, though.

Fragments

Merging fragments can lead to a multitude of problems, none of which are detected as a conflict in LemonTree:

• overlapping fragments
• resizing of fragments, leading to messages either "falling into" or "falling out of" a fragment

An example for a merge resulting in overlapping fragments can be seen in this figure:

Figure 8: Overlapping fragments because of concurrent edits

Recommendation

Merges of fragments currently require a manual review of the merge result in all cases.

Using filters to analyze changes on sequence diagrams

It is possible to use the Filter Feature in order to better understand the changes made on sequence diagrams.

The following example is given:
In one of the diffed versions, a new sequence message was added. The sequence message was added between other existing messages, which leads to a reordering of the message displayed below the new message.
If you want to find out, which sequence messages have been added only and not modified by the automatic reordering, you can use the following filter:

NOT UmlType: ea\_Diagram AND NOT ChangeIn: "EA Specifics 1.0::SeqNo" AND NOT ChangeIn: "EA Specifics 1.0::PDATA5" $HideGraphicalChanges $OnlyMatchingChildElements 

This will reduce the Tree Browser and the Impacted Diagrams List to the newly added connectors and with their connecting elements.

If you want to also hide the lifelines / components / ports that are shown as changed (because there was a new link added to them), you can use the following filter:

NOT UmlType: ea\_Diagram AND NOT ChangeIn: "EA Specifics 1.0::SeqNo" AND NOT ChangeIn: "EA Specifics 1.0::PDATA5" AND NOT UmlType: InstanceSpecification AND NOT UmlType: Component AND NOT UmlType: Port $HideGraphicalChanges $OnlyMatchingChildElements

With this filter, the Tree Browser and the Impacted Diagrams List is reduced to all sequence messages, that were added to the diagram.

Source

The original source (in german) is available here: 
Sequenzdiagramme_LemonTree.pdf

The models mentioned in the article can be downloaded here:

ATM.zip

Inconsistencies of Sequence Diagrams

If a sequence connector has the Diagram_ID set to 0 it will show the connector on every diagram where the source and target object is present. But as soon as one changes something about this connector (or just saves the diagram in EA), the Diagram_ID will be set. This internally will now lead EA to show this specific sequence connector only on the diagram specified ('removing' it from all other diagrams).

This will lead inevitably to a malformed models/diagrams. Since we can't make this decision for the user, we need to flag this as an inconsistency and only let the user do the cleanup. The good thing is LemonTree already shows "the real model" and will also not change the Diagram_ID (not even during merge) so the user can do the cleanup before or after merge.

Users can use the following SQL query to find sequence messages that do not have the Diagram_ID set in the t_connector tabel.

SELECT tob.* FROM t_connector tc, t_object tob WHERE Connector_Type = 'Sequence' AND tc.DiagramID = '0' AND tob.Object_ID = tc.Start_Object_ID GROUP by tob.ea_guid

Step by Step guide in Enterprise Architect

• open the model
• open the Find in Project feature (Start -> (Explore) -> Search -> Model)
• create a new search (first icon in the toolbar on the right)
• in the New Search dialog select SQL Editor (name can be left emtpy)
• click OK
• select the SQL Scratch Pad tab
• copy the sql query into the SQL Scratch Pad
• click on Run Sql or press F5
• the list below will now contain all elements that have an invalid message sequence connector between them
• select an entry from the list and right click to open the context menu
• use the Find in Diagrams feature
• change something (may be as simple as the position of a label or element)
• save the changed diagram
• go back to the Find in Project tab and
• repeat steps 8. to 14. until no more entries are found