Compare for BranchManager for DOORSŪ
BranchManager for DOORS provides a powerful comparison mechanism to identify differences between baselines and across branches. Its intelligent comparison engine can compare based on a selectable list of attributes, and can detect changes in attributes, OLE objects, links, and structural changes such as moving a requirement in the hierarchy.
Understanding the Compare
Object Matching
The compare feature of BranchManager is designed to find the differences between any modules A and B. The comparison algorithm works at the object level, i.e. BranchManager will first find which object in module A corresponds to which module in B. This is called the "matching phase". For the matching, BranchManager does not yet feature the possibility of trying to guess the matching object by content. Therefore the user must supply BranchManager with a way on how to match the objects of both modules. The following possibilities exist:
- Match By Attribute
If in both modules there are two attributes that have a unique matching reference, then BranchManager can use these attributes to match up the objects. This is the most common case in any data exchange scenario. In the easiest scenario, you have two modules, that are copies of each other and they contain the same Absolute Number. In this case you can use the Absolute Number to match the objects. In another scenario you might have exported a module to Excel, made some changes and imported back to a new module. In the new module, the objects might get new Absolute Numbers, but if you exported and imported the original Absolute Number of the objects and stored it in an attribute, you can use this attribute to match the objects. Notice that in two baselines of the same module, the objects can always be matched by using the Absolute Number.

- Match By Link
If in both modules, the objects are linked 1:1, then objects can be matched using this link. This scenario is common, when for example modules have been copied using Copy-And-Link or in cases where custom DXL scripts are used to maintain parallel requirements distributed across multiple modules. Another way for using this matching is to use the DOORS Compare feature to get two modules without any common identifier matched by content. The link direction or link module does not matter in this case. BranchManager will take into account links in both directions.

- Match By Branch Reference Identifier
Matching objects of two modules by Branch Reference is like matching up the modules by attribute, with an important difference. Although BranchManager stores the Branch Identifier of an object in the "BranchManager Internal Reference Long" attribute, this attribute cannot be used to match the objects of two modules. The real Branch Reference is calculated from this attribute on the fly, taking into account that an object can have an empty or invalid attribute value - in this case a new unique identifier will be calculated. When matching objects by Branch Reference Identifier, this calculated identifier is used, making sure that also baselines which do not even have the BranchManager Internal Reference Long attribute can be used and no errors due to copy paste will occur.
Before and After - The directed, two way compare
It is important to understand that the results of the comparison in BranchManager yields a 'Difference', i.e. a list of changes to bring one module to the same content as another module. For this, BranchManager assumes that the two modules have really originated from the same module or baseline and that one of the compared modules contains the 'old' state, i.e. before any changes have been performed and the other module contains the 'after' state, i.e. after all changes have been applied. It is important to understand that there is no reliable way to detect in which module a change has actually been performed (there is no change history in all cases)
Example:
Object Text in Module A: This is a requirement
Object Text in Module B: There is no requirement here.
If A is the older module and B is the newer module, then the result could be: This There is a no requirement here.
which says that the words "This" and "a" have been deleted and the words "There", "no" and "here." have been inserted.
If B is the older module and A is the newer module, then the result could be: This There is no a requirement here.
which says that the words "There", "no" and "here." have been deleted, while the words "This" and "a" have been inserted.
Depending on what module is supposed to be the older module, the result of the compare could be inverted. In fact, we cannot tell from the above example which of the changes really occurred. It could also be that both modules have been changed - that here was a different text in both modules before the change and that after the change, the text of both module is as above. In this situation the result of the comparison might seem illogical or even wrong. This can be most confusing when one looks at the result of creating / deleting objects or links.
If in module A, an object exists and in module B there is no corresponding object found, then it could be either that:
- the object has been created in module A (module A is newer, i.e. after change, module B is older, i.e. before change)
- the object has been removed from module B (module B is newer, i.e. after change, module A is older, i.e. before change)
Depending on what module has been selected as older, BranchManager might now gives as a result: "The object in module A has been deleted", which could surprise a user that might know that he never deleted an object - that he even did not change anything in module A. In this case the compare settings must be adapted to correctly reflect the sides before and after the changes. In cases where changes have been performed on both sides, it can be hard to read the comparison results, since some changes will be inverted and some will not be inverted. Note that this problem also affects the two-way-merge (quick merge) but not the three-way-merge (integration).
Which changes are identified by BranchManager?
The compare feature of BranchManager was designed to give a complete set of changes that have been performed to a DOORS module. That includes:
- Creating objects
- Soft deleting objects
- Purging deleted objects
- Adding / deleting / modifying a DOORS picture
- Changing a module or object attribute:
- formatting change
- content change
- OLE object change
- Creating or Deleting a DOORS Link
- Moving a DOORS object
Note that the comparison only refers to the content of the modules. Changes of the data model are at the moment not part of the comparison, i.e. changed link pairings, views, access permissions, attributes, and changes to types if they do not affect the content. If however the user changes the default value of an attribute, which will result in a change of attribute values for all objects that have the default value, this change will show up during the content comparison, as if the change has been applied manually. A change in enumeration values (e.g. the addition of an enumeration value for a type) will only affect comparison if the attribute value of an object is changed.
OLE Comparison Details
OLE Comparison in DOORS is a feature that is not easy to realize in DOORS. The native DOORS comparison or other products in many cases will not compare OLE objects, due to a bug in DOORS. Due to this bug, the actual raw data of an OLE object changes if that OLE is copied, baselined or even if it is read multiple times with reopening the module in-between (even though it did not change in between the reads).
BranchManager compares OLE objects by examining the visual part of the OLE object and the length of the data part. Using this comparison algorithm, BranchManager has in the past never failed to identify a change to an OLE object. Visible changes, i.e. changes that result in a difference in the displayed picture are detected with 100% accuracy. There exists the possibility of 'invisible changes' to an OLE object, e.g. an embedded Excel Table can have data that is outside the displayed area, e.g. in a hidden worksheet inside the OLE object. A non-visible change is detected using the comparison of the data length, which in the past also has never failed. However it might be worth knowing that the very unlikely and most probably unimportant case of an invisible change (i.e. the user will not see any difference!) that does not change the size of the data of the OLE object will not be detected by the Comparison of BranchManager.
Understanding Hierarchy Comparison
With the detection of the movements of objects, the same rules that have been described in the section Before and After apply. With structural comparison, it is however more likely that the detected changes do not reflect the exact modifications that have been performed. The reason for this is that a structural change is likely to be ambiguous, i.e. the same result can be achieved in more than one way. That means that while BranchManager will give a 100% accurate and valid result for the detection of movements, it can occur that the result might not reflect what the user has really done to get to the current state of the module.
Example
To explain this, lets look at a very simple example with two modules that each contain 5 top level objects without any hierarchy:

From the picture it can be seen that object 3 and 4 have been exchanged, however this could have happened in two ways (with only one move):
- The user could have moved object 3 after object 4
- The user could have moved object 4 after object 2
It can be seen from this very simple example that BranchManager has no way of knowing which of these changes actually occurred. However in this case this will likely not pose a problem since the result of both changes is the same and therefore not only technically but also from a content perspective it is hard to imagine a situation where the fact which object has been moved matters in this simple case.
In case of ambiguous movements, BranchManager will always show the first minimal movement set that results in the 'After' state. A minimal movement means that in some cases the same result can be achieved by movements of a different number of objects. If for example in the above picture, someone moved object 5 to the top of the module, this could also be achieved by moving objects 1,2,3 and 4 after object 5. The second movement however involves 4 objects, instead of 1 object. In this case BranchManager always shows the minimal variant, i.e. the one with the least number of objects needed to be moved. If, as in the above example, the movements both involve the same number of objects, then the object that first occurs in the module will show the change.
Note that ambiguity only applies to the movements of objects below the same parent (or on top level). For objects that move to a new parent, the situation is usually not ambiguous:

In the above case, the only way to reach the 'After' state is to move object 4 below object 2.
Understanding Link Comparison
The link comparison of BranchManager is an algorithm that determines changes to the Out-Links of a DOORS module. Fitting to the concept of Links in DOORS, the change of an In-Link is a change to the module where the link originates. Therefore Branch Managere only compares the DOORS links that originate from each matched object. Note that in DOORS, neither the target nor the source of a link can be changed. Therefore BranchManager only knows two changes:
- Creating a Link
- Deleting a Link
Technically, links in DOORS can contain attributes which can be changed (e.g. as used for the suspect link feature of DOORS). BranchManager does not compare the attributes of links. Also at the moment, BranchManager does not support comparison of external links. BranchManager also does not consider the link module of a link, since this is considered a part of the data model.
To determine which links are created and deleted, BranchManager looks at the existing links on the before and after side for each matched object pair. When a link exists on the "before" side which does not exist on the "after" side, then this link is considered to be deleted. If a link exists on the after side which does not exist on the source side, then these links are considered to be created.
Example:

From the picture above, it can be seen that the links marked with 3 and 4 have been deleted, while the link 6 was newly created. Of course the same rules that have been described in the section Before and After apply here.
The link comparison in BranchManager has to deal with the problem that the target of a link can be any object in the database. Therefore the question arises when a link is equal to another link and when not. Of course, when the links on a "Before" and "After" object point to exactly the same object, then it is easy to say that a link is equal. However there are scenarios with baselining, copying, data exchange, where the links do NOT point to exactly the same object. This section describes the scenarios in which the link comparison of BranchManager will still work, although the target of compared links are not the same.
Links to different Baselines of the same target
Especially when working with baseline sets, the links in a baseline compare will point to different target baselines of the same target module. Branch Manager is able to compare the links of two baselines, even though the links inside the baselines point to different objects. In the picture below, BranchManager determines the target module version for the "Before" baseline to be baseline 1.0 and the target module version for the "After" module to be the current version. This allows BranchManager to detect link changes in the most common baselining use cases. However from time to time it happens that there might be some links from one of the source modules to both baselines. If that happens, BranchManager decides for a desired target module version by taking the module version to which the most links point. So imagine for whatever reason in the picture before that there would be one link from the "After" module (current) to Baseline 1.0 of the target module, then the link comparison would still work, since BranchManager still correctly would identify the current version of the target module as the desired target for the after module.

Links from different source modules to the same target module
When working with copy paste or some custom parallel development scenarios, a situation like this can occur:

There are two different modules for "Before" and "After", but both contain links to the same target module (same baseline or different, the same rule as described in the previous paragraph apply). Since the "Before" and "After" are matched up (by link or by attribute), BranchManager can determine the link changes that have happened between before and after correctly.
Links to different target modules
There is one situation, where link comparison cannot determine if two links as equal. When the link targets of "Before" and "After" are in different modules which are not in a Branch, then the compare does not allow the user to specify a matching method for each link target. In this case BranchManager will fail to see two links as being equal and therefore report all links to be deleted and recreated:

Links inside different Branches
If "Before" and "After" side modules are parallel modules in different branches (see Understanding Branches), then BranchManager can match the link targets that are in the same branch as the "Before" / "After" module. When a link points from the Branch to an outside project, then BranchManager can match the links, as long as they point to the same module (different versions are possible).
Understanding Comparison Messages
One must take into account that the Compare application of BranchManager allows you to view the changes on either module - the before module or the after module. The comparison results depend on the side from which the change is viewed. If for example an object was deleted (i.e. it exists on the before side and it does not exist on the after side), then if this change is viewed from the before side, BranchManager can state "this object was deleted". If however the same changed is viewed from the after side, then there is no object where BranchManager can show the message, so BranchManager will go to the previous object that still exists and show a message there: "An object (ID: xy) was deleted here". For the simple case of an attribute difference, BranchManager will simply show the redlined difference. The following picture shows the different comparison messages for the cases of object/link creation or deletion. Note that "Object on before side" and "Object on after side" will be replaced by the identifier and module of the affected object.